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
68 URI definition for different VNF’s
69 ==================================
72 +---------------------------------+-----------+--------------------------+----------------------------------------------------+
73 | *URI* | *Method* | *Arguments* | *description* |
74 +---------------------------------+-----------+--------------------------+----------------------------------------------------+
75 | */vnf* | GET | None | Displays top level methods available |
76 +---------------------------------+-----------+--------------------------+----------------------------------------------------+
77 | */vnf/config* | GET | None | Displays the current config set |
78 +---------------------------------+-----------+--------------------------+----------------------------------------------------+
79 | */vnf/config* | POST | | |
80 | | | pci_white_list | |
81 | | | num_worker(o) | |
83 | | | pkt_type (o) | |
87 | | | hyperthread(o) | |
88 +---------------------------------+-----------+--------------------------+----------------------------------------------------+
89 | */vnf/config/arp* | GET | None | Displays ARP/ND info |
90 +---------------------------------+-----------+--------------------------+----------------------------------------------------+
91 | */vnf/config/arp* | POST | action: <add/del/req> | |
92 | | | ipv4/ipv6: <address> | |
94 | | | macaddr: <> for add | |
95 +---------------------------------+-----------+--------------------------+----------------------------------------------------+
96 | */vnf/config/link* | GET | None | |
97 +---------------------------------+-----------+--------------------------+----------------------------------------------------+
98 | */vnf/config/link* | POST | link_id:<> | |
99 | | | state: <1/0> | |
100 +---------------------------------+-----------+--------------------------+----------------------------------------------------+
101 | */vnf/config/link/<link id>* | GET | None | |
102 +---------------------------------+-----------+--------------------------+----------------------------------------------------+
103 | */vnf/config/link/<link id>* | POST | ipv4/ipv6: <address> | |
105 +---------------------------------+-----------+--------------------------+----------------------------------------------------+
106 | */vnf/config/route* | GET | None | Displays gateway route entries |
107 +---------------------------------+-----------+--------------------------+----------------------------------------------------+
108 | */vnf/config/route* | POST | portid: <> | Adds route entries for default gateway |
109 | | | nhipv4/nhipv6: <addr> | |
111 | | | type:"net/host" | |
112 +---------------------------------+-----------+--------------------------+----------------------------------------------------+
113 | */vnf/config/rules(vFW/vACL)* | GET | None | Displays the methods /load/clear |
114 +---------------------------------+-----------+--------------------------+----------------------------------------------------+
115 | */vnf/config/rules/load* | GET | None | Displays if file was loaded |
116 +---------------------------------+-----------+--------------------------+----------------------------------------------------+
117 | */vnf/config/rules/load* | PUT | <script file | |
118 | | | with cmds> | Executes each command from script file |
119 +---------------------------------+-----------+--------------------------+----------------------------------------------------+
120 | */vnf/config/rules/clear* | GET | None | |
121 +---------------------------------+-----------+--------------------------+----------------------------------------------------+
122 | */vnf/config/nat(vCGNAPT only)* | GET | None | Displays the methods /load/clear |
123 +---------------------------------+-----------+--------------------------+----------------------------------------------------+
124 | */vnf/config/nat/load* | GET | None | Displays if file was loaded |
125 +---------------------------------+-----------+--------------------------+----------------------------------------------------+
126 | */vnf/config/rules/load* | PUT | <script file with cmds> | |
127 +---------------------------------+-----------+--------------------------+----------------------------------------------------+
128 | */vnf/config/nat/clear* | GET | None | |
129 +---------------------------------+-----------+--------------------------+----------------------------------------------------+
130 | */vnf/log* | GET | None | This needs to be implemented for each VNF |
131 | | | | just keeping this as placeholder. |
132 +---------------------------------+-----------+--------------------------+----------------------------------------------------+
133 | */vnf/dbg* | GET | None | Will display methods supported like /pipelines/cmd |
134 +---------------------------------+-----------+--------------------------+----------------------------------------------------+
135 | */vnf/dbg/pipelines* | GET | None | Displays pipeline information(names) |
136 +---------------------------------+-----------+--------------------------+----------------------------------------------------+
137 | */vnf/dbg/pipelines/<pipe id>* | GET | None | Displays debug level for particular pipeline |
138 +---------------------------------+-----------+--------------------------+----------------------------------------------------+
139 | */vnf/dbg/cmd* | GET | None | Last executed command parameters |
140 +---------------------------------+-----------+--------------------------+----------------------------------------------------+
141 | */vnf/dbg/cmd* | POST | cmd: | |
145 +---------------------------------+-----------+--------------------------+----------------------------------------------------+
147 PUT/POST - Command success/failure
155 An application(say vFW) with REST API support is run as follows
156 with just PORT MASK as input. The following environment variables
157 need to be set before launching the application(To be run from
158 samplevnf directory).
161 ./build/vFW (Without the -f & -s option)
163 1. When VNF(vCGNAPT/vACL/vFW) is launched it waits for user to provide the /vnf/config REST method.
165 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
167 Note: the config is mostly implemented based on existing VNF's. if new parameters
168 are required in the config we need to add that as part of the vnf_template.
170 Once the config is provided the application gets launched.
172 Note for CGNAPT we can add public_ip_port_range as follows, the following e.g gives
173 a multiport configuration with 4 ports, 2 load balancers, worker threads 10, multiple
174 public_ip_port_range being added, please note the "/" being used to seperate multiple
175 inputs for public_ip_port_range.
177 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",
178 "num_lb":"2", "num_worker":"10","public_ip_port_range_0": "04040000:(1, 65535)/04040001:(1, 65535)",
179 "public_ip_port_range_1": "05050000:(1, 65535)/05050001:(1, 65535)" }' http://10.223.197.179/vnf/config
181 2. Check the Link IP's using the REST API (vCGNAPT/vACL/vFW)
183 e.g curl <IP>/vnf/config/link
185 This would indicate the number of links enabled. You should enable all the links
186 by using following curl command for links 0 & 1
188 e.g curl -X POST -H "Content-Type:application/json" -d '{"linkid": "0", "state": "1"}'
189 http://<IP>/vnf/config/link
190 curl -X POST -H "Content-Type:application/json" -d '{"linkid": "1", "state": "1"}'
191 http://<IP>/vnf/config/link
193 3. Now that links are enabled we can configure IP's using link method as follows (vCGNAPT/vACL/vFW)
195 e.g curl -X POST -H "Content-Type:application/json" -d '{"ipv4":"<IP to be configured>","depth":"24"}'
196 http://<IP>/vnf/config/link/0
197 curl -X POST -H "Content-Type:application/json" -d '{"ipv4":"IP to be configured","depth":"24"}'
198 http://<IP>/vnf/config/link/1
200 Once the IP's are set in place time to add NHIP for ARP Table. This is done using for all the ports required.
203 curl -X POST -H "Content-Type:application/json" -d '{"portid":"0", "nhipv4":"IPV4 address",
204 "depth":"8", "type":"net"}' http://<IP>/vnf/config/route
206 4. Adding arp entries we can use this method (vCGNAPT/vACL/vFW)
211 curl -X POST -H "Content-Type:application/json" -d '{"action":"add", "ipv4":"202.16.100.20",
212 "portid":"0", "macaddr":"00:00:00:00:00:01"}'
213 http://10.223.166.213/vnf/config/arp
215 curl -X POST -H "Content-Type:application/json" -d '{"action":"add", "ipv4":"172.16.40.20",
216 "portid":"1", "macaddr":"00:00:00:00:00:02"}'
217 http://10.223.166.213/vnf/config/arp
219 5. Adding route entries we can use this method (vCGNAPT/vACL/vFW)
223 e.g curl -X POST -H "Content-Type:application/json" -d '{"type":"net", "depth":"8", "nhipv4":"202.16.100.20",
224 "portid":"0"}' http://10.223.166.240/vnf/config/route
225 curl -X POST -H "Content-Type:application/json" -d '{"type":"net", "depth":8", "nhipv4":"172.16.100.20",
226 "portid":"1"}' http://10.223.166.240/vnf/config/route
228 5. In order to load the rules a script file needs to be posting a script.(vACL/vFW)
230 /vnf/config/rules/load
232 Typical example for loading a script file is shown below
233 curl -X PUT -F 'image=@<path to file>' http://<IP>/vnf/config/rules/load
235 typically arpadd/routeadd commands can be provided as part of this to
236 add static arp entries & adding route entries providing the NHIP's.
238 6. The following REST api's for runtime configuring through a script (vCGNAPT Only)
240 /vnf/config/rules/clear
244 7. For debug purpose following REST API's could be used as described above.(vCGNAPT/vACL/vFW)
247 e.g curl http://10.223.166.240/vnf/config/dbg
250 e.g curl http://10.223.166.240/vnf/config/dbg/pipelines
252 /vnf/dbg/pipelines/<pipe id>
253 e.g curl http://10.223.166.240/vnf/config/dbg/pipelines/<id>
257 8. For stats we can use the following method (vCGNAPT/vACL/vFW)
260 e.g curl <IP>/vnf/stats
262 9. For quittiong the application (vCGNAPT/vACL/vFW)
265 e.g curl <IP>/vnf/quit