docs/testing/user/userguide/server.rst

   1 .. This work is licensed under a Creative Commons Attribution 4.0 International License.
   2 .. SPDX-License-Identifier: CC-BY-4.0
   3 .. (c) Cisco Systems, Inc
   4
   5 NFVbench Server mode and NFVbench client API
   6 ============================================
   7
   8 NFVbench can run as an HTTP server to:
   9
  10 - optionally provide access to any arbitrary HTLM files (HTTP server function) - this is optional
  11 - service fully parameterized aynchronous run requests using the HTTP protocol (REST/json with polling)
  12 - service fully parameterized run requests with interval stats reporting using the WebSocket/SocketIO protocol.
  13
  14 Start the NFVbench server
  15 -------------------------
  16 To run in server mode, simply use the --server <http_root_path> and optionally the listen address to use (--host <ip>, default is 0.0.0.0) and listening port to use (--port <port>, default is 7555).
  17
  18
  19 If HTTP files are to be serviced, they must be stored right under the http root path.
  20 This root path must contain a static folder to hold static files (css, js) and a templates folder with at least an index.html file to hold the template of the index.html file to be used.
  21 This mode is convenient when you do not already have a WEB server hosting the UI front end.
  22 If HTTP files servicing is not needed (REST only or WebSocket/SocketIO mode), the root path can point to any dummy folder.
  23
  24 Once started, the NFVbench server will be ready to service HTTP or WebSocket/SocketIO requests at the advertised URL.
  25
  26 Example of NFVbench server start in a container:
  27
  28 .. code-block:: bash
  29
  30     # get to the container shell (assume the container name is "nfvbench")
  31     docker exec -it nfvbench bash
  32     # from the container shell start the NFVbench server in the background
  33     nfvbench -c /tmp/nfvbench/nfvbench.cfg --server /tmp &
  34     # exit container
  35     exit
  36
  37
  38
  39 HTTP Interface
  40 --------------
  41
  42 <http-url>/echo (GET)
  43 ^^^^^^^^^^^^^^^^^^^^^
  44
  45 This request simply returns whatever content is sent in the body of the request (only used for testing)
  46
  47 <http-url>/start_run (POST)
  48 ^^^^^^^^^^^^^^^^^^^^^^^^^^^
  49
  50 This request will initiate a new NFVbench run asynchornously and can optionally pass the NFVbench configuration to run in the body (in JSON format).
  51 See "NFVbench configuration JSON parameter" below for details on how to format this parameter.
  52
  53 The request returns immediately with a json content indicating if there was an error (status=ERROR) or if the request was submitted successfully (status=PENDING). Example of return when the submission is successful:
  54
  55 .. code-block:: bash
  56
  57     {
  58       "error_message": "nfvbench run still pending",
  59       "status": "PENDING"
  60     }
  61
  62 <http-url>/status (GET)
  63 ^^^^^^^^^^^^^^^^^^^^^^^
  64
  65 This request fetches the status of an asynchronous run. It will return in json format:
  66
  67 - a request pending reply (if the run is still not completed)
  68 - an error reply if there is no run pending
  69 - or the complete result of the run
  70
  71 The client can keep polling until the run completes.
  72
  73 Example of return when the run is still pending:
  74
  75 .. code-block:: bash
  76
  77     {
  78       "error_message": "nfvbench run still pending",
  79       "status": "PENDING"
  80     }
  81
  82 Example of return when the run completes:
  83
  84 .. code-block:: bash
  85
  86     {
  87       "result": {...}
  88       "status": "OK"
  89     }
  90
  91
  92
  93 WebSocket/SocketIO events
  94 -------------------------
  95
  96 List of SocketIO events supported:
  97
  98 Client to Server
  99 ^^^^^^^^^^^^^^^^
 100
 101 start_run:
 102
 103     sent by client to start a new run with the configuration passed in argument (JSON).
 104     The configuration can be any valid NFVbench configuration passed as a JSON document (see "NFVbench configuration JSON parameter" below)
 105
 106 Server to Client
 107 ^^^^^^^^^^^^^^^^
 108
 109 run_interval_stats:
 110
 111     sent by server to report statistics during a run
 112     the message contains the statistics {'time_ms': time_ms, 'tx_pps': tx_pps, 'rx_pps': rx_pps, 'drop_pct': drop_pct}
 113
 114 ndr_found:
 115
 116     (during NDR-PDR search)
 117     sent by server when the NDR rate is found
 118     the message contains the NDR value {'rate_pps': ndr_pps}
 119
 120 ndr_found:
 121
 122     (during NDR-PDR search)
 123     sent by server when the PDR rate is found
 124     the message contains the PDR value {'rate_pps': pdr_pps}
 125
 126
 127 run_end:
 128
 129     sent by server to report the end of a run
 130     the message contains the complete results in JSON format
 131
 132 NFVbench configuration JSON parameter
 133 -------------------------------------
 134 The NFVbench configuration describes the parameters of an NFVbench run and can be passed to the NFVbench server as a JSON document.
 135
 136 Default configuration
 137 ^^^^^^^^^^^^^^^^^^^^^
 138
 139 The simplest JSON document is the empty dictionary "{}" which indicates to use the default NFVbench configuration:
 140
 141 - PVP
 142 - NDR-PDR measurement
 143 - 64 byte packets
 144 - 1 flow per direction
 145
 146 The entire default configuration can be viewed using the --show-json-config option on the cli:
 147
 148 .. code-block:: bash
 149
 150     # nfvbench --show-json-config
 151     {
 152         "availability_zone": null,
 153         "compute_node_user": "root",
 154         "compute_nodes": null,
 155         "debug": false,
 156         "duration_sec": 60,
 157         "flavor": {
 158             "disk": 0,
 159             "extra_specs": {
 160                 "hw:cpu_policy": "dedicated",
 161                 "hw:mem_page_size": 2048
 162             },
 163             "ram": 8192,
 164             "vcpus": 2
 165         },
 166         "flavor_type": "nfv.medium",
 167         "flow_count": 1,
 168         "generic_poll_sec": 2,
 169         "generic_retry_count": 100,
 170         "image_name": "nfvbenchvm",
 171         "inter_node": false,
 172         "internal_networks": {
 173             "left": {
 174                 "name": "nfvbench-net0",
 175                 "subnet": "nfvbench-subnet0",
 176                 "cidr": "192.168.1.0/24",
 177             },
 178             "right": {
 179                 "name": "nfvbench-net1",
 180                 "subnet": "nfvbench-subnet1",
 181                 "cidr": "192.168.2.0/24",
 182             },
 183             "middle": {
 184                 "name": "nfvbench-net2",
 185                 "subnet": "nfvbench-subnet2",
 186                 "cidr": "192.168.3.0/24",
 187             }
 188         },
 189         "interval_sec": 10,
 190         "json": null,
 191         "loop_vm_name": "nfvbench-loop-vm",
 192         "measurement": {
 193             "NDR": 0.001,
 194             "PDR": 0.1,
 195             "load_epsilon": 0.1
 196         },
 197         "name": "(built-in default config)",
 198         "no_cleanup": false,
 199         "no_int_config": false,
 200         "no_reset": false,
 201         "no_tor_access": false,
 202         "no_traffic": false,
 203         "no_vswitch_access": false,
 204         "openrc_file": "/tmp/nfvbench/openstack/openrc",
 205         "openstack_defaults": "/tmp/nfvbench/openstack/defaults.yaml",
 206         "openstack_setup": "/tmp/nfvbench/openstack/setup_data.yaml",
 207         "rate": "ndr_pdr",
 208         "service_chain": "PVP",
 209         "service_chain_count": 1,
 210         "sriov": false,
 211         "std_json": null,
 212         "tor": {
 213             "switches": [
 214                 {
 215                     "host": "172.26.233.12",
 216                     "password": "lab",
 217                     "port": 22,
 218                     "username": "admin"
 219                 }
 220             ],
 221             "type": "N9K"
 222         },
 223         "traffic": {
 224             "bidirectional": true,
 225             "profile": "traffic_profile_64B"
 226         },
 227         "traffic_generator": {
 228             "default_profile": "trex-local",
 229             "gateway_ip_addrs": [
 230                 "1.1.0.2",
 231                 "2.2.0.2"
 232             ],
 233             "gateway_ip_addrs_step": "0.0.0.1",
 234             "generator_profile": [
 235                 {
 236                     "cores": 3,
 237                     "interfaces": [
 238                         {
 239                             "pci": "0a:00.0",
 240                             "port": 0,
 241                             "switch_port": "Ethernet1/33",
 242                             "vlan": null
 243                         },
 244                         {
 245                             "pci": "0a:00.1",
 246                             "port": 1,
 247                             "switch_port": "Ethernet1/34",
 248                             "vlan": null
 249                         }
 250                     ],
 251                     "intf_speed": "10Gbps",
 252                     "ip": "127.0.0.1",
 253                     "name": "trex-local",
 254                     "tool": "TRex"
 255                 }
 256             ],
 257             "host_name": "nfvbench_tg",
 258             "ip_addrs": [
 259                 "10.0.0.0/8",
 260                 "20.0.0.0/8"
 261             ],
 262             "ip_addrs_step": "0.0.0.1",
 263             "mac_addrs": [
 264                 "00:10:94:00:0A:00",
 265                 "00:11:94:00:0A:00"
 266             ],
 267             "step_mac": null,
 268             "tg_gateway_ip_addrs": [
 269                 "1.1.0.100",
 270                 "2.2.0.100"
 271             ],
 272             "tg_gateway_ip_addrs_step": "0.0.0.1"
 273         },
 274         "traffic_profile": [
 275             {
 276                 "l2frame_size": [
 277                     "64"
 278                 ],
 279                 "name": "traffic_profile_64B"
 280             },
 281             {
 282                 "l2frame_size": [
 283                     "IMIX"
 284                 ],
 285                 "name": "traffic_profile_IMIX"
 286             },
 287             {
 288                 "l2frame_size": [
 289                     "1518"
 290                 ],
 291                 "name": "traffic_profile_1518B"
 292             },
 293             {
 294                 "l2frame_size": [
 295                     "64",
 296                     "IMIX",
 297                     "1518"
 298                 ],
 299                 "name": "traffic_profile_3sizes"
 300             }
 301         ],
 302         "unidir_reverse_traffic_pps": 1,
 303         "vlan_tagging": true,
 304         "vm_image_file": "file://172.29.172.152/downloads/nfvbench/nfvbenchvm-latest.qcow2",
 305         "vts_ncs": {
 306             "host": null,
 307             "password": "secret",
 308             "port": 22,
 309             "username": "admin"
 310         }
 311     }
 312
 313
 314 Common examples of JSON configuration
 315 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 316
 317 Use the default configuration but use 10000 flows per direction (instead of 1):
 318
 319 .. code-block:: bash
 320
 321     { "flow_count": 10000 }
 322
 323
 324 Use default confguration but with 10000 flows, "EXT" chain and IMIX packet size:
 325
 326 .. code-block:: bash
 327
 328     {
 329        "flow_count": 10000,
 330        "service_chain": "EXT",
 331         "traffic": {
 332             "profile": "traffic_profile_IMIX"
 333         },
 334     }
 335
 336 A short run of 5 seconds at a fixed rate of 1Mpps (and everything else same as the default configuration):
 337
 338 .. code-block:: bash
 339
 340     {
 341        "duration": 5,
 342        "rate": "1Mpps"
 343     }
 344
 345 Example of interaction with the NFVbench server using HTTP and curl
 346 -------------------------------------------------------------------
 347 HTTP requests can be sent directly to the NFVbench server from CLI using curl from any host that can connect to the server (here we run it from the local host).
 348
 349 This is a POST request to start a run using the default NFVbench configuration but with traffic generation disabled ("no_traffic" property is set to true):
 350
 351 .. code-block:: bash
 352
 353     [root@sjc04-pod3-mgmt ~]# curl -H "Accept: application/json" -H "Content-type: application/json" -X POST -d '{"no_traffic":true}' http://127.0.0.1:7555/start_run
 354     {
 355       "error_message": "nfvbench run still pending",
 356       "status": "PENDING"
 357     }
 358     [root@sjc04-pod3-mgmt ~]#
 359
 360 This request will return immediately with status set to "PENDING" if the request was started successfully.
 361
 362 The status can be polled until the run completes. Here the poll returns a "PENDING" status, indicating the run is still not completed:
 363
 364 .. code-block:: bash
 365
 366     [root@sjc04-pod3-mgmt ~]# curl -G http://127.0.0.1:7555/status
 367     {
 368       "error_message": "nfvbench run still pending",
 369       "status": "PENDING"
 370     }
 371     [root@sjc04-pod3-mgmt ~]#
 372
 373 Finally, the status request returns a "OK" status along with the full results (truncated here):
 374
 375 .. code-block:: bash
 376
 377     [root@sjc04-pod3-mgmt ~]# curl -G http://127.0.0.1:7555/status
 378     {
 379       "result": {
 380         "benchmarks": {
 381           "network": {
 382             "service_chain": {
 383               "PVP": {
 384                 "result": {
 385                   "bidirectional": true,
 386                   "compute_nodes": {
 387                     "nova:sjc04-pod3-compute-4": {
 388                       "bios_settings": {
 389                         "Adjacent Cache Line Prefetcher": "Disabled",
 390                         "All Onboard LOM Ports": "Enabled",
 391                         "All PCIe Slots OptionROM": "Enabled",
 392                         "Altitude": "300 M",
 393     ...
 394
 395         "date": "2017-03-31 22:15:41",
 396         "nfvbench_version": "0.3.5",
 397         "openstack_spec": {
 398           "encaps": "VxLAN",
 399           "vswitch": "VTS"
 400         }
 401       },
 402       "status": "OK"
 403     }
 404     [root@sjc04-pod3-mgmt ~]#
 405
 406
 407
 408 Example of interaction with the NFVbench server using a python CLI app (nfvbench_client)
 409 ----------------------------------------------------------------------------------------
 410 The module client/client.py contains an example of python class that can be used to control the NFVbench server from a python app using HTTP or WebSocket/SocketIO.
 411
 412 The module client/nfvbench_client.py has a simple main application to control the NFVbench server from CLI.
 413 The "nfvbench_client" wrapper script can be used to invoke the client front end (this wrapper is pre-installed in the NFVbench container)
 414
 415 Example of invocation of the nfvbench_client front end, from the host (assume the name of the NFVbench container is "nfvbench"),
 416 use the default NFVbench configuration but do not generate traffic (no_traffic property set to true, the full json result is truncated here):
 417
 418 .. code-block:: bash
 419
 420     [root@sjc04-pod3-mgmt ~]# docker exec -it nfvbench nfvbench_client -c '{"no_traffic":true}' http://127.0.0.1:7555
 421     {u'status': u'PENDING', u'error_message': u'nfvbench run still pending'}
 422     {u'status': u'PENDING', u'error_message': u'nfvbench run still pending'}
 423     {u'status': u'PENDING', u'error_message': u'nfvbench run still pending'}
 424
 425     {u'status': u'OK', u'result': {u'date': u'2017-03-31 22:04:59', u'nfvbench_version': u'0.3.5',
 426     u'config': {u'compute_nodes': None, u'compute_node_user': u'root', u'vts_ncs': {u'username': u'admin', u'host': None, u'password': u'secret', u'port': 22}, u'traffic_generator': {u'tg_gateway_ip_addrs': [u'1.1.0.100', u'2.2.0.100'], u'ip_addrs_step': u'0.0.0.1', u'step_mac': None, u'generator_profile': [{u'intf_speed': u'10Gbps', u'interfaces': [{u'pci': u'0a:00.0', u'port': 0, u'vlan': 1998, u'switch_port': None},
 427
 428     ...
 429
 430     [root@sjc04-pod3-mgmt ~]#
 431
 432 The http interface is used unless --use-socketio is defined.
 433
 434 Example of invocation using Websocket/SocketIO, execute NFVbench using the default configuration but with a duration of 5 seconds and a fixed rate run of 5kpps.
 435
 436 .. code-block:: bash
 437
 438     [root@sjc04-pod3-mgmt ~]# docker exec -it nfvbench nfvbench_client -c '{"duration":5,"rate":"5kpps"}' --use-socketio  http://127.0.0.1:7555 >results.json
 439
 440
 441
 442
 443
 444
 445