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 | 323 |
1 files changed, 137 insertions, 186 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..658f99d3 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,7 +4,7 @@ .. (c) opnfv, national center of scientific research "demokritos" and others. ======================================================== -REST API - Readme +REST API ======================================================== Introduction @@ -65,128 +65,81 @@ 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: +---------------------------------- +:: + +---------------------------------+-----------------+--------------------------+----------------------------------------------------+ + | **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: | | + | | | 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> | | + | | | ipv4/ipv6: <address> | | + | | | portid: <> | | + | | | macaddr: <> for add | | + +---------------------------------+-----------------+--------------------------+----------------------------------------------------+ + |/vnf/config/link | GET | None | | + | | POST | link_id:<> | | + | | | state: <1/0> | | + +---------------------------------+-----------------+--------------------------+----------------------------------------------------+ + |/vnf/config/link/<link id> | GET | None | | + | | POST | ipv4/ipv6: <address> | | + | | | 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 | | + +---------------------------------+-----------------+--------------------------+----------------------------------------------------+ + |/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 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 | + | | POST | cmd: | | + | | | dbg: | | + | | | d1: | | + | | | d2: | | + +---------------------------------+-----------------+--------------------------+----------------------------------------------------+ + + PUT/POST - Command success/failure 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 +1. Run time Usage ==================== An application(say vFW) with REST API support is run as follows @@ -194,114 +147,112 @@ 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. -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 -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 -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 <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 + 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 |