aboutsummaryrefslogtreecommitdiffstats
path: root/docs/testing/user/userguide/server.rst
blob: 52645adcc9f2e072257cd5793b81426951499365 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
.. This work is licensed under a Creative Commons Attribution 4.0 International License.
.. SPDX-License-Identifier: CC-BY-4.0
.. (c) Cisco Systems, Inc

NFVbench Server mode and NFVbench client API
============================================


HTTP Interface
--------------

<http-url>/echo (GET)
^^^^^^^^^^^^^^^^^^^^^

This request simply returns whatever content is sent in the body of the request (body should be in json format, only used for testing)

Example request:

.. code-block:: bash

    curl -XGET '127.0.0.1:7555/echo' -H "Content-Type: application/json" -d '{"nfvbench": "test"}'
    Response:
    {
      "nfvbench": "test"
    }


<http-url>/status (GET)
^^^^^^^^^^^^^^^^^^^^^^^

This request fetches the status of an asynchronous run. It will return in json format:

- a request pending reply (if the run is still not completed)
- an error reply if there is no run pending
- or the complete result of the run

The client can keep polling until the run completes.

Example of return when the run is still pending:

.. code-block:: bash

    {
      "error_message": "nfvbench run still pending",
      "status": "PENDING"
    }

Example of return when the run completes:

.. code-block:: bash

    {
      "result": {...}
      "status": "OK"
    }


<http-url>/start_run (POST)
^^^^^^^^^^^^^^^^^^^^^^^^^^^

This request starts an NFVBench run with passed configurations. If no configuration is passed, a run with default configurations will be executed.

Example request: curl -XPOST 'localhost:7556/start_run' -H "Content-Type: application/json" -d @nfvbenchconfig.json

See "NFVbench configuration JSON parameter" below for details on how to format this parameter.

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:

.. code-block:: bash

    {
      "error_message": "NFVbench run still pending",
      "request_id": "42cccb7effdc43caa47f722f0ca8ec96",
      "status": "PENDING"
    }

If there is already an NFVBench running then it will return:

.. code-block:: bash

    {
     "error_message": "there is already an NFVbench request running",
     "status": "ERROR"
    }


NFVbench configuration JSON parameter
-------------------------------------
The NFVbench configuration describes the parameters of an NFVbench run and can be passed to the NFVbench server as a JSON document.

Default configuration
^^^^^^^^^^^^^^^^^^^^^

The simplest JSON document is the empty dictionary "{}" which indicates to use the default NFVbench configuration:

- PVP
- NDR-PDR measurement
- 64 byte packets
- 1 flow per direction

The entire default configuration can be viewed using the --show-json-config option on the cli:

.. code-block:: bash

    # nfvbench --show-config
    {
        "availability_zone": null,
        "compute_node_user": "root",
        "compute_nodes": null,
        "debug": false,
        "duration_sec": 60,
        "flavor": {
            "disk": 0,
            "extra_specs": {
                "hw:cpu_policy": "dedicated",
                "hw:mem_page_size": 2048
            },
            "ram": 8192,
            "vcpus": 2
        },
        "flavor_type": "nfv.medium",
        "flow_count": 1,
        "generic_poll_sec": 2,
        "generic_retry_count": 100,
        "inter_node": false,
        "internal_networks": {
            "left": {
                "name": "nfvbench-net0",
                "subnet": "nfvbench-subnet0",
                "cidr": "192.168.1.0/24",
            },
            "right": {
                "name": "nfvbench-net1",
                "subnet": "nfvbench-subnet1",
                "cidr": "192.168.2.0/24",
            },
            "middle": {
                "name": "nfvbench-net2",
                "subnet": "nfvbench-subnet2",
                "cidr": "192.168.3.0/24",
            }
        },
        "interval_sec": 10,
        "json": null,
        "loop_vm_name": "nfvbench-loop-vm",
        "measurement": {
            "NDR": 0.001,
            "PDR": 0.1,
            "load_epsilon": 0.1
        },
        "name": "(built-in default config)",
        "no_cleanup": false,
        "no_traffic": false,
        "openrc_file": "/tmp/nfvbench/openstack/openrc",
        "rate": "ndr_pdr",
        "service_chain": "PVP",
        "service_chain_count": 1,
        "sriov": false,
        "std_json": null,
        "traffic": {
            "bidirectional": true,
            "profile": "traffic_profile_64B"
        },
        "traffic_generator": {
            "default_profile": "trex-local",
            "gateway_ip_addrs": [
                "1.1.0.2",
                "2.2.0.2"
            ],
            "gateway_ip_addrs_step": "0.0.0.1",
            "generator_profile": [
                {
                    "cores": 3,
                    "interfaces": [
                        {
                            "pci": "0a:00.0",
                            "port": 0,
                            "switch_port": "Ethernet1/33",
                            "vlan": null
                        },
                        {
                            "pci": "0a:00.1",
                            "port": 1,
                            "switch_port": "Ethernet1/34",
                            "vlan": null
                        }
                    ],
                    "intf_speed": null,
                    "ip": "127.0.0.1",
                    "name": "trex-local",
                    "tool": "TRex"
                }
            ],
            "host_name": "nfvbench_tg",
            "ip_addrs": [
                "10.0.0.0/8",
                "20.0.0.0/8"
            ],
            "ip_addrs_step": "0.0.0.1",
            "mac_addrs": [
                "00:10:94:00:0A:00",
                "00:11:94:00:0A:00"
            ],
            "step_mac": null,
            "tg_gateway_ip_addrs": [
                "1.1.0.100",
                "2.2.0.100"
            ],
            "tg_gateway_ip_addrs_step": "0.0.0.1"
        },
        "traffic_profile": [
            {
                "l2frame_size": [
                    "64"
                ],
                "name": "traffic_profile_64B"
            },
            {
                "l2frame_size": [
                    "IMIX"
                ],
                "name": "traffic_profile_IMIX"
            },
            {
                "l2frame_size": [
                    "1518"
                ],
                "name": "traffic_profile_1518B"
            },
            {
                "l2frame_size": [
                    "64",
                    "IMIX",
                    "1518"
                ],
                "name": "traffic_profile_3sizes"
            }
        ],
        "unidir_reverse_traffic_pps": 1,
        "vlan_tagging": true,
    }


Common examples of JSON configuration
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Use the default configuration but use 10000 flows per direction (instead of 1):

.. code-block:: bash

    { "flow_count": 10000 }


Use default confguration but with 10000 flows, "EXT" chain and IMIX packet size:

.. code-block:: bash

    {
       "flow_count": 10000,
       "service_chain": "EXT",
        "traffic": {
            "profile": "traffic_profile_IMIX"
        },
    }

A short run of 5 seconds at a fixed rate of 1Mpps (and everything else same as the default configuration):

.. code-block:: bash

    {
       "duration": 5,
       "rate": "1Mpps"
    }

Use the default configuration but force TRex restart:

.. code-block:: bash

    {
       "restart": true
    }


Example of interaction with the NFVbench server using HTTP and curl
-------------------------------------------------------------------
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).

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):

.. code-block:: bash

    [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
    {
      "error_message": "nfvbench run still pending",
      "status": "PENDING"
    }
    [root@sjc04-pod3-mgmt ~]#

This request will return immediately with status set to "PENDING" if the request was started successfully.

The status can be polled until the run completes. Here the poll returns a "PENDING" status, indicating the run is still not completed:

.. code-block:: bash

    [root@sjc04-pod3-mgmt ~]# curl -G http://127.0.0.1:7555/status
    {
      "error_message": "nfvbench run still pending",
      "status": "PENDING"
    }
    [root@sjc04-pod3-mgmt ~]#

Finally, the status request returns a "OK" status along with the full results (truncated here):

.. code-block:: bash

    [root@sjc04-pod3-mgmt ~]# curl -G http://127.0.0.1:7555/status
    {
      "result": {
        "benchmarks": {
          "network": {
            "service_chain": {
              "PVP": {
                "result": {
                  "bidirectional": true,
                  "compute_nodes": {
                    "nova:sjc04-pod3-compute-4": {
                      "bios_settings": {
                        "Adjacent Cache Line Prefetcher": "Disabled",
                        "All Onboard LOM Ports": "Enabled",
                        "All PCIe Slots OptionROM": "Enabled",
                        "Altitude": "300 M",
    ...

        "date": "2017-03-31 22:15:41",
        "nfvbench_version": "0.3.5",
        "openstack_spec": {
          "encaps": "VxLAN",
          "vswitch": "VTS"
        }
      },
      "status": "OK"
    }
    [root@sjc04-pod3-mgmt ~]#



Example of interaction with the NFVbench server using a python CLI app (nfvbench_client)
----------------------------------------------------------------------------------------
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.

The module client/nfvbench_client.py has a simple main application to control the NFVbench server from CLI.
The "nfvbench_client" wrapper script can be used to invoke the client front end (this wrapper is pre-installed in the NFVbench container)

Example of invocation of the nfvbench_client front end, from the host (assume the name of the NFVbench container is "nfvbench"),
use the default NFVbench configuration but do not generate traffic (no_traffic property set to true, the full json result is truncated here):

.. code-block:: bash

    [root@sjc04-pod3-mgmt ~]# docker exec -it nfvbench nfvbench_client -c '{"no_traffic":true}' http://127.0.0.1:7555
    {u'status': u'PENDING', u'error_message': u'nfvbench run still pending'}
    {u'status': u'PENDING', u'error_message': u'nfvbench run still pending'}
    {u'status': u'PENDING', u'error_message': u'nfvbench run still pending'}

    {u'status': u'OK', u'result': {u'date': u'2017-03-31 22:04:59', u'nfvbench_version': u'0.3.5',
     u'config': {u'compute_nodes': None, u'compute_node_user': u'root', 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'', u'interfaces': [{u'pci': u'0a:00.0', u'port': 0, u'vlan': 1998, u'switch_port': None},

    ...

    [root@sjc04-pod3-mgmt ~]#