summaryrefslogtreecommitdiffstats
path: root/docs/testing/user/userguide/06-How_to_use_REST_api.rst
blob: 5372646482662fa29da4ef42016bd59561f92f9d (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
.. This work is licensed under a creative commons attribution 4.0 international
.. license.
.. http://creativecommons.org/licenses/by/4.0
.. (c) opnfv, national center of scientific research "demokritos" and others.

========================================================
REST API - Readme
========================================================

Introduction
===============
As the internet industry progresses creating REST API becomes more concrete
with emerging best Practices. RESTful web services don’t follow a prescribed
standard except fpr the protocol that is used which is HTTP, its important
to build RESTful API in accordance with industry best practices to ease
development & increase client adoption.

In REST Architecture everything is a resource. RESTful web services are light
weight, highly scalable and maintainable and are very commonly used to
create APIs for web-based applications.

Here are important points to be considered:

 * GET operations are read only and are safe.
 * PUT and DELETE operations are idempotent means their result will
   always same no matter how many times these operations are invoked.
 * PUT and POST operation are nearly same with the difference lying
   only in the result where PUT operation is idempotent and POST
    operation can cause different result.


REST API in SampleVNF
=====================

In SampleVNF project VNF’s are run under different contexts like BareMetal,
SRIOV, OVS & Openstack etc. It becomes difficult to interact with the
VNF’s using the command line interface provided by the VNF’s currently.

Hence there is a need to provide a web interface to the VNF’s running in
different environments through the REST api’s. REST can be used to modify
or view resources on the server without performing any server-side
operations.

REST api on VNF’s will help adapting with the new automation techniques
being adapted in yardstick.

Web server integration with VNF’s
==================================

In order to implement REST api’s in VNF one of the first task is to
identify a simple web server that needs to be integrated with VNF’s.
For this purpose “civetweb” is identified as the web server That will
be integrated with the VNF application.

CivetWeb is an easy to use, powerful, C/C++ embeddable web server with
optional CGI, SSL and Lua support. CivetWeb can be used by developers
as a library, to add web server functionality to an existing application.

Civetweb is a project forked out of Mongoose. CivetWeb uses an [MITlicense].
It can also be used by end users as a stand-alone web server. It is available
as single executable, no installation is required.

In our project we will be integrating civetweb into each of our VNF’s.
Civetweb exposes a few functions which are used to resgister custom handlers
for different URI’s that are implemented.
Typical usage is shown below


VNF Application init()
=========================

Initialize the civetweb library
================================

mg_init_library(0);

Start the web server
=====================
ctx = mg_start(NULL, 0, options);


Once the civetweb server is started we can register our URI’s as show below
mg_set_request_handler(ctx, "/config", static_cfg_handler, 0);

In the above example “/config” is the URI & static_cfg_handler() is
the handler that gets called when a user invokes this URI through
the HTTP client. API's have been mostly implemented for existing VNF's
like vCGNAPT, vFW & vACL. you might want to implement custom handlers
for your VNF.

URI definition for different VNF’s
===================================


URI           				REST Method	     Arguments			Description
===========================================================================================================================
/vnf                  			GET  		       	None           		Displays top level methods available

/vnf/config           			GET         		None           		Displays the current config set
                                        POST                    pci_white_list:         Command success/failure
                                                                num_worker(o):
                                                                vnf_type(o):
                                                                pkt_type (o):
                                                                num_lb(o):
                                                                sw_lb(o):
                                                                sock_in(o):
                                                                hyperthread(o) :

/vnf/config/arp                         GET                     None                    Displays ARP/ND info
                                        POST                    action: <add/del/req>   Command success/failure
                                                                ipv4/ipv6: <address>
                                                                portid: <>
                                                                macaddr: <> for add

/vnf/config/link                        GET                     None
                                        POST                    link_id:<>              Command success/failure
                                                                state: <1/0>

/vnf/config/link/<link id>              GET                     None
                                        POST                    ipv4/ipv6: <address>    Command success/failure
                                                                depth: <>


/vnf/config/route                       GET                     None                    Displays gateway route entries
                                        POST                    portid: <>              Adds route entries for default gateway
                                                                nhipv4/nhipv6: <addr>
                                                                depth: <>
                                                                type:"net/host"

/vnf/config/rules(vFW/vACL only)        GET                     None                    Displays the methods /load/clear
/vnf/config/rules/load                  GET                     None                    Displays if file was loaded
                                        PUT                     <script file
                                                                with cmds>              Executes each command from script file
/vnf/config/rules/clear                 GET                     None                    Command success/failure clear the stat

/vnf/config/nat(vCGNAPT only)           GET                     None                    Displays the methods /load/clear
/vnf/config/nat/load                    GET                     None                    Displays if file was loaded
                                        PUT                     <script file
                                                                 with commands>         Executes each command from script file

/vnf/config/nat/clear                   GET                     None                    Command success/failure clear the stats
/vnf/log                                GET                     None                    This needs to be implemented for each VNF
                                                                                        just keeping this as placeholder.

/vnf/dbg                                GET                     None                    Will display methods supported like /pipelines/cmd
/vnf/dbg/pipelines                      GET                     None                    Displays pipeline information(names)
                                                                                        of each pipelines
/vnf/dbg/pipelines/<pipe id>            GET                     None                    Displays debug level for particular pipeline

/vnf/dbg/cmd                            GET                     None                    Last executed command parameters
                                        POST                    cmd:                    Command success/failure
                                                                dbg:
                                                                d1:
                                                                d2:

API Usage
===============

1. Initialization
================

In order to integrate to your VNF these are the steps required

In your VNF application init


#ifdef REST_API_SUPPORT
        Initialize the rest api
        struct mg_context *ctx = rest_api_init(&app);
#endif


#ifdef REST_API_SUPPORT
        rest api's for cgnapt
        rest_api_<vnf>_init(ctx, &app);
#endif


void rest_api_<vnf>_init(struct mg_context *ctx, struct app_params *app)
{
        myapp = app;

        VNF specific command registration
        mg_set_request_handler(,,,);

}


2. Run time Usage
====================

An application(say vFW) with REST API support is run as follows
with just PORT MASK as input. The following environment variables
need to be set before launching the application(To be run from
samplevnf directory).

export VNF_CORE=`pwd`
export RTE_SDK=`pwd`/dpdk-16.04
export RTE_TARGET=x86_64-native-linuxapp-gcc

./build/vFW (Without the -f & -s option)

1. When VNF(vCGNAPT/vACL/vFW) is launched it waits for user to provide the
/vnf/config REST method. A typical curl command if used will look like below
shown. This with minimal parameter. For more options please refer to above REST
methods table.

e.g curl -X POST -H "Content-Type:application/json" -d '{"pci_white_list": "0000:08:00.0
 0000:08:00.1"}' http://<IP>/vnf/config

Note: the config is mostly implemented based on existing VNF's. if new parameters
are required in the config we need to add that as part of the vnf_template.

Once the config is provided the application gets launched.

Note for CGNAPT we can add public_ip_port_range as follows, the following e.g gives
a multiport configuration with 4 ports, 2 load balancers, worker threads 10, multiple
public_ip_port_range being added, please note the "/" being used to seperate multiple
inputs for public_ip_port_range.

e.g curl -X POST -H "Content-Type:application/json" -d '{"pci_white_list": "0000:05:00.0 0000:05:00.2 0000:07:00.0 0000:07:00.2",
                "num_lb":"2", "num_worker":"10","public_ip_port_range_0": "04040000:(1, 65535)/04040001:(1, 65535)",
                "public_ip_port_range_1": "05050000:(1, 65535)/05050001:(1, 65535)" }' http://10.223.197.179/vnf/config

2. Check the Link IP's using the REST API (vCGNAPT/vACL/vFW)
e.g curl <IP>/vnf/config/link

This would indicate the number of links enabled. You should enable all the links
by using following curl command for links 0 & 1

e.g curl -X POST -H "Content-Type:application/json" -d '{"linkid": "0", "state": "1"}'
http://<IP>/vnf/config/link
curl -X POST -H "Content-Type:application/json" -d '{"linkid": "1", "state": "1"}'
http://<IP>/vnf/config/link

3. Now that links are enabled we can configure IP's using link method as follows (vCGNAPT/vACL/vFW)

e.g  curl -X POST -H "Content-Type:application/json" -d '{"ipv4":"<IP to be configured>","depth":"24"}'
http://<IP>/vnf/config/link/0
curl -X POST -H "Content-Type:application/json" -d '{"ipv4":"IP to be configured","depth":"24"}'
http://<IP>/vnf/config/link/1

Once the IP's are set in place time to add NHIP for ARP Table. This is done using for all the ports
required.
/vnf/config/route

curl -X POST -H "Content-Type:application/json" -d '{"portid":"0", "nhipv4":"IPV4 address",
 "depth":"8", "type":"net"}' http://<IP>/vnf/config/route

4. Adding arp entries we can use this method (vCGNAPT/vACL/vFW)
/vnf/config/arp

e.g

curl -X POST -H "Content-Type:application/json" -d '{"action":"add", "ipv4":"202.16.100.20",
                 "portid":"0", "macaddr":"00:00:00:00:00:01"}'
                 http://10.223.166.213/vnf/config/arp

curl -X POST -H "Content-Type:application/json" -d '{"action":"add", "ipv4":"172.16.40.20",
                 "portid":"1", "macaddr":"00:00:00:00:00:02"}'
                 http://10.223.166.213/vnf/config/arp

5. Adding route entries we can use this method (vCGNAPT/vACL/vFW)
vnf/config/route

e.g curl -X POST -H "Content-Type:application/json" -d '{"type":"net", "depth":"8", "nhipv4":"202.16.100.20",
                  "portid":"0"}' http://10.223.166.240/vnf/config/route
curl -X POST -H "Content-Type:application/json" -d '{"type":"net", "depth":8", "nhipv4":"172.16.100.20",
                 "portid":"1"}' http://10.223.166.240/vnf/config/route

5. In order to load the rules a script file needs to be posting a script.(vACL/vFW)
/vnf/config/rules/load

Typical example for loading a script file is shown below
curl -X PUT -F 'image=@<path to file>' http://<IP>/vnf/config/rules/load

typically arpadd/routeadd commands can be provided as part of this to
add static arp entries & adding route entries providing the NHIP's.

6. The following REST api's for runtime configuring through a script (vCGNAPT Only)
/vnf/config/rules/clear
/vnf/config/nat
/vnf/config/nat/load

7. For debug purpose following REST API's could be used as described above.(vCGNAPT/vACL/vFW)

/vnf/dbg

e.g curl http://10.223.166.240/vnf/config/dbg

/vnf/dbg/pipelines
e.g curl http://10.223.166.240/vnf/config/dbg/pipelines

/vnf/dbg/pipelines/<pipe id>
e.g curl http://10.223.166.240/vnf/config/dbg/pipelines/<id>

/vnf/dbg/cmd

8. For stats we can use the following method (vCGNAPT/vACL/vFW)

/vnf/stats
e.g curl <IP>/vnf/stats

9. For quittiong the application (vCGNAPT/vACL/vFW)
/vnf/quit

e.g curl <IP>/vnf/quit