diff options
Diffstat (limited to 'docs/testing/user/userguide/06-How_to_use_REST_api.rst')
| -rw-r--r-- | docs/testing/user/userguide/06-How_to_use_REST_api.rst | 340 |
1 files changed, 150 insertions, 190 deletions
diff --git a/docs/testing/user/userguide/06-How_to_use_REST_api.rst b/docs/testing/user/userguide/06-How_to_use_REST_api.rst index 53726464..b8c0cbea 100644 --- a/docs/testing/user/userguide/06-How_to_use_REST_api.rst +++ b/docs/testing/user/userguide/06-How_to_use_REST_api.rst @@ -4,11 +4,11 @@ .. (c) opnfv, national center of scientific research "demokritos" and others. ======================================================== -REST API - Readme +REST API ======================================================== 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 @@ -30,7 +30,7 @@ Here are important points to be considered: 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 @@ -45,7 +45,7 @@ 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. @@ -65,243 +65,203 @@ 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(,,,); -} ++---------------------------------+-----------+--------------------------+----------------------------------------------------+ +| *URI* | *Method* | *Arguments* | *description* | ++---------------------------------+-----------+--------------------------+----------------------------------------------------+ +| */vnf* | GET | None | Displays top level methods available | ++---------------------------------+-----------+--------------------------+----------------------------------------------------+ +| */vnf/config* | GET | None | Displays the current config set | ++---------------------------------+-----------+--------------------------+----------------------------------------------------+ +| */vnf/config* | POST | | | +| | | pci_white_list | | +| | | 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 | ++---------------------------------+-----------+--------------------------+----------------------------------------------------+ +| */vnf/config/arp* | POST | action: <add/del/req> | | +| | | ipv4/ipv6: <address> | | +| | | portid: <> | | +| | | macaddr: <> for add | | ++---------------------------------+-----------+--------------------------+----------------------------------------------------+ +| */vnf/config/link* | GET | None | | ++---------------------------------+-----------+--------------------------+----------------------------------------------------+ +| */vnf/config/link* | POST | link_id:<> | | +| | | state: <1/0> | | ++---------------------------------+-----------+--------------------------+----------------------------------------------------+ +| */vnf/config/link/<link id>* | GET | None | | ++---------------------------------+-----------+--------------------------+----------------------------------------------------+ +| */vnf/config/link/<link id>* | POST | ipv4/ipv6: <address> | | +| | | depth: <> | | ++---------------------------------+-----------+--------------------------+----------------------------------------------------+ +| */vnf/config/route* | GET | None | Displays gateway route entries | ++---------------------------------+-----------+--------------------------+----------------------------------------------------+ +| */vnf/config/route* | POST | portid: <> | Adds route entries for default gateway | +| | | nhipv4/nhipv6: <addr> | | +| | | depth: <> | | +| | | type:"net/host" | | ++---------------------------------+-----------+--------------------------+----------------------------------------------------+ +| */vnf/config/rules(vFW/vACL)* | GET | None | Displays the methods /load/clear | ++---------------------------------+-----------+--------------------------+----------------------------------------------------+ +| */vnf/config/rules/load* | GET | None | Displays if file was loaded | ++---------------------------------+-----------+--------------------------+----------------------------------------------------+ +| */vnf/config/rules/load* | PUT | <script file | | +| | | with cmds> | Executes each command from script file | ++---------------------------------+-----------+--------------------------+----------------------------------------------------+ +| */vnf/config/rules/clear* | GET | None | | ++---------------------------------+-----------+--------------------------+----------------------------------------------------+ +| */vnf/config/nat(vCGNAPT only)* | GET | None | Displays the methods /load/clear | ++---------------------------------+-----------+--------------------------+----------------------------------------------------+ +| */vnf/config/nat/load* | GET | None | Displays if file was loaded | ++---------------------------------+-----------+--------------------------+----------------------------------------------------+ +| */vnf/config/rules/load* | PUT | <script file with cmds> | | ++---------------------------------+-----------+--------------------------+----------------------------------------------------+ +| */vnf/config/nat/clear* | GET | None | | ++---------------------------------+-----------+--------------------------+----------------------------------------------------+ +| */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) | ++---------------------------------+-----------+--------------------------+----------------------------------------------------+ +| */vnf/dbg/pipelines/<pipe id>* | GET | None | Displays debug level for particular pipeline | ++---------------------------------+-----------+--------------------------+----------------------------------------------------+ +| */vnf/dbg/cmd* | GET | None | Last executed command parameters | ++---------------------------------+-----------+--------------------------+----------------------------------------------------+ +| */vnf/dbg/cmd* | POST | cmd: | | +| | | dbg: | | +| | | d1: | | +| | | d2: | | ++---------------------------------+-----------+--------------------------+----------------------------------------------------+ + + PUT/POST - Command success/failure +API Usage +--------- -2. Run time Usage -==================== +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) + ./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. +1. When VNF(vCGNAPT/vACL/vFW) is launched it waits for user to provide the /vnf/config REST method. + :: -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 + 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. + 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. + 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. + 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 + 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 + :: + 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 + 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 + 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 -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 + 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 + 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 + :: + /vnf/config/arp -e.g - -curl -X POST -H "Content-Type:application/json" -d '{"action":"add", "ipv4":"202.16.100.20", + 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", + 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 + :: + /vnf/config/route -e.g curl -X POST -H "Content-Type:application/json" -d '{"type":"net", "depth":"8", "nhipv4":"202.16.100.20", + 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", + 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 + :: + /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 + 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. + 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 + :: + /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 - -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 -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/pipelines/<pipe id> -e.g curl http://10.223.166.240/vnf/config/dbg/pipelines/<id> - -/vnf/dbg/cmd + /vnf/dbg/cmd 8. For stats we can use the following method (vCGNAPT/vACL/vFW) - -/vnf/stats -e.g curl <IP>/vnf/stats + :: + /vnf/stats + e.g curl <IP>/vnf/stats 9. For quittiong the application (vCGNAPT/vACL/vFW) -/vnf/quit - -e.g curl <IP>/vnf/quit + :: + /vnf/quit + e.g curl <IP>/vnf/quit |