1 .. This work is licensed under a creative commons attribution 4.0 international
3 .. http://creativecommons.org/licenses/by/4.0
4 .. (c) opnfv, national center of scientific research "demokritos" and others.
6 ========================================================
8 ========================================================
12 As the internet industry progresses creating REST API becomes more concrete
13 with emerging best Practices. RESTful web services don’t follow a prescribed
14 standard except fpr the protocol that is used which is HTTP, its important
15 to build RESTful API in accordance with industry best practices to ease
16 development & increase client adoption.
18 In REST Architecture everything is a resource. RESTful web services are light
19 weight, highly scalable and maintainable and are very commonly used to
20 create APIs for web-based applications.
22 Here are important points to be considered:
24 * GET operations are read only and are safe.
25 * PUT and DELETE operations are idempotent means their result will
26 always same no matter how many times these operations are invoked.
27 * PUT and POST operation are nearly same with the difference lying
28 only in the result where PUT operation is idempotent and POST
29 operation can cause different result.
35 In SampleVNF project VNF’s are run under different contexts like BareMetal,
36 SRIOV, OVS & Openstack etc. It becomes difficult to interact with the
37 VNF’s using the command line interface provided by the VNF’s currently.
39 Hence there is a need to provide a web interface to the VNF’s running in
40 different environments through the REST api’s. REST can be used to modify
41 or view resources on the server without performing any server-side
44 REST api on VNF’s will help adapting with the new automation techniques
45 being adapted in yardstick.
47 Web server integration with VNF’s
48 ==================================
50 In order to implement REST api’s in VNF one of the first task is to
51 identify a simple web server that needs to be integrated with VNF’s.
52 For this purpose “civetweb” is identified as the web server That will
53 be integrated with the VNF application.
55 CivetWeb is an easy to use, powerful, C/C++ embeddable web server with
56 optional CGI, SSL and Lua support. CivetWeb can be used by developers
57 as a library, to add web server functionality to an existing application.
59 Civetweb is a project forked out of Mongoose. CivetWeb uses an [MITlicense].
60 It can also be used by end users as a stand-alone web server. It is available
61 as single executable, no installation is required.
63 In our project we will be integrating civetweb into each of our VNF’s.
64 Civetweb exposes a few functions which are used to resgister custom handlers
65 for different URI’s that are implemented.
66 Typical usage is shown below
69 VNF Application init()
70 =========================
72 Initialize the civetweb library
73 ================================
79 ctx = mg_start(NULL, 0, options);
82 Once the civetweb server is started we can register our URI’s as show below
83 mg_set_request_handler(ctx, "/config", static_cfg_handler, 0);
85 In the above example “/config” is the URI & static_cfg_handler() is
86 the handler that gets called when a user invokes this URI through
87 the HTTP client. API's have been mostly implemented for existing VNF's
88 like vCGNAPT, vFW & vACL. you might want to implement custom handlers
91 URI definition for different VNF’s
92 ===================================
96 URI REST Method Arguments Description
97 ===========================================================================================================================
98 /vnf GET None Displays top level methods available
100 /vnf/config GET None Displays the current config set
101 POST pci_white_list: Command success/failure
110 /vnf/config/arp GET None Displays ARP/ND info
111 POST action: <add/del/req> Command success/failure
116 /vnf/config/link GET None
117 POST link_id:<> Command success/failure
120 /vnf/config/link/<link id> GET None
121 POST Command success/failure
125 /vnf/config/route GET None Displays gateway route entries
126 POST portid: <> Adds route entries for default gateway
127 nhipv4/nhipv6: <addr>
131 /vnf/config/rules(vFW/vACL only) GET None Displays the methods /load/clear
132 /vnf/config/rules/load GET None Displays if file was loaded
134 with cmds> Executes each command from script file
135 /vnf/config/rules/clear GET None Command success/failure clear the stat
137 /vnf/config/nat(vCGNAPT only) GET None Displays the methods /load/clear
138 /vnf/config/nat/load GET None Displays if file was loaded
140 with commands> Executes each command from script file
142 /vnf/config/nat/clear GET None Command success/failure clear the stats
143 /vnf/log GET None This needs to be implemented for each VNF
144 just keeping this as placeholder.
146 /vnf/dbg GET None Will display methods supported like /pipelines/cmd
147 /vnf/dbg/pipelines GET None Displays pipeline information(names)
149 /vnf/dbg/pipelines/<pipe id> GET None Displays debug level for particular pipeline
151 /vnf/dbg/cmd GET None Last executed command parameters
152 POST cmd: Command success/failure
163 In order to integrate to your VNF these are the steps required
165 In your VNF application init
168 #ifdef REST_API_SUPPORT
169 Initialize the rest api
170 struct mg_context *ctx = rest_api_init(&app);
174 #ifdef REST_API_SUPPORT
175 rest api's for cgnapt
176 rest_api_<vnf>_init(ctx, &app);
180 void rest_api_<vnf>_init(struct mg_context *ctx, struct app_params *app)
184 VNF specific command registration
185 mg_set_request_handler(,,,);
193 An application(say vFW) with REST API support is run as follows
194 with just PORT MASK as input. The following environment variables
195 need to be set before launching the application(To be run from
196 samplevnf directory).
198 export VNF_CORE=`pwd`
199 export RTE_SDK=`pwd`/dpdk-16.04
200 export RTE_TARGET=x86_64-native-linuxapp-gcc
202 ./build/vFW -p 0x3 (Without the -f & -s option)
204 1. When VNF(vCGNAPT/vACL/vFW) is launched it waits for user to provide the
205 /vnf/config REST method. A typical curl command if used will look like below
206 shown. This with minimal parameter. For more options please refer to above REST
209 e.g curl -X POST -H "Content-Type:application/json" -d '{"pci_white_list": "0000:08:00.0
210 0000:08:00.1"}' http://<IP>/vnf/config
212 Note: the config is mostly implemented based on existing VNF's. if new parameters
213 are required in the config we need to add that as part of the vnf_template.
215 Once the config is provided the application gets launched.
217 Note for CGNAPT we can add public_ip_port_range as follows, the following e.g gives
218 a multiport configuration with 4 ports, 2 load balancers, worker threads 10, multiple
219 public_ip_port_range being added, please note the "/" being used to seperate multiple
220 inputs for public_ip_port_range.
222 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",
223 "num_lb":"2", "num_worker":"10","public_ip_port_range_0": "04040000:(1, 65535)/04040001:(1, 65535)",
224 "public_ip_port_range_1": "05050000:(1, 65535)/05050001:(1, 65535)" }' http://10.223.197.179/vnf/config
226 2. Check the Link IP's using the REST API
227 e.g curl <IP>/vnf/config/link
229 This would indicate the number of links enabled. You should enable all the links
230 by using following curl command for links 0 & 1
232 e.g curl -X POST -H "Content-Type:application/json" -d '{"linkid": "0", "state": "1"}'
233 http://<IP>/vnf/config/link
234 curl -X POST -H "Content-Type:application/json" -d '{"linkid": "1", "state": "1"}'
235 http://<IP>/vnf/config/link
237 3. Now that links are enabled we can configure IP's using link method as follows
239 e.g curl -X POST -H "Content-Type:application/json" -d '{"ipv4":"<IP to be configured>","depth":"24"}'
240 http://<IP>/vnf/config/link/0
241 curl -X POST -H "Content-Type:application/json" -d '{"ipv4":"IP to be configured","depth":"24"}'
242 http://<IP>/vnf/config/link/1
244 Once the IP's are set in place time to add NHIP for ARP Table. This is done using for all the ports
248 curl -X POST -H "Content-Type:application/json" -d '{"portid":"0", "nhipv4":"IPV4 address",
249 "depth":"8", "type":"net"}' http://<IP>/vnf/config/route
252 4. For Firewall/ACL in order to load the rules a script file needs to be posted
254 /vnf/config/rules/load
256 Typical example for loading a script file is shown below
257 curl -X PUT -F 'image=@<path to file>' http://<IP>/vnf/config/rules/load
259 vCGNAPT can use the following REST api's for runtime configuring through a script
260 /vnf/config/rules/clear
261 /vnf/config/nat(vCGNAPT only)
264 For debug purpose following REST API's could be used as described above.
268 /vnf/dbg/pipelines/<pipe id>
271 5. For stats we can use the following method
274 e.g curl <IP>/vnf/stats
276 6. For quittiong the application
279 e.g curl <IP>/vnf/quit