A "Virtual Service" is a combination of a Virtual IP (VIP) address and a TCP port, which listens and directs the traffic to the intended service.
To Create a Virtual Service
URL: /v1/virtual_services | |||
Method: POST | |||
Description: Creates a virtual service with the given values. | |||
Parameter Name | Data Type | Mandatory | Description |
---|---|---|---|
Input Parameters: | |||
name | Alphanumeric | Yes | The name of the new service. |
ip_address | Numeric | Yes | The virtual IP address that will be used for accessing this application. |
port | Numeric | Yes | The port number on which your web server responds. |
type | Enumeration | Yes | The type of the service you want to create. The enumerated values include:
|
address_version | Enumeration | Yes | The internet protocol version of the service. The enumerated values include:
|
vsite | Alphanumeric | Optional | The name of the vsite under which the service needs to be created. Note: This field is required ONLY when the service needs to be created under a specific vsite. If not, the service will be created under the default vsite. |
group | Alphanumeric | Optional | The name of the service group under which the service needs to be created. Note: This field is required ONLY when the service needs to be created under a specific service group. If not, the service will be created under the default service group. |
certificate | Alphanumeric | Conditional | The certificate that needs to be presented to the browser when accessing this Service. Note: This is a required parameter ONLY when the service is HTTPS, Instant SSL, Custom SSL or FTP SSL. |
service_hostname | Alphanumeric | Conditional | The domain name to identify and rewrite HTTP requests to HTTPS. Note: This is a required parameter ONLY when the service is Instant SSL. |
Output Parameters: | |||
id | Alphanumeric | The name of the service that got created. |
Example: HTTP Service
Request:
curl http://192.168.0.1:8000/restapi/v1/virtual_services -u 'eyJldCI6IjEzNzk2NDA4MzciLCJwYXNzd29yZCI6ImIxZjQzYmVhZTk5MWFmMWUyNDYzYTFiNjA5\nYzYzZTFjIiwidXNlciI6ImFkbWluIn0=\n:' -X POST -H Content-Type:application/json -d '{"name": "demo_service_3", "ip_address": "10.11.16.176", "port": "80", "type":"http", "address_version":"ipv4", "vsite":"demo_vsite", "group":"demo_vsite_group"}'
Response:
{"id":"demo_service_3","token":"eyJldCI6IjEzNzk2NTIyNjEiLCJwYXNzd29yZCI6ImRiODUwZDMxZjYzNTQ4Njk2MzdhZDZiZThl\nMTQzODMxIiwidXNlciI6ImFkbWluIn0=\n"}
Example: HTTPS Service
Request:
curl http://192.168.0.1:8000/restapi/v1/virtual_services -u 'eyJldCI6IjEzNzk1OTYwOTAiLCJwYXNzd29yZCI6ImIxMzJiMmI2MmI3ZDYzYTc0NTU5M2UzNTFm\nNzMxMTEwIiwidXNlciI6ImFkbWluIn0=\n:' -X POST -H Content-Type:application/json –d '{"certificate":"cert1","address_version":"ipv4","name":"demo_service_2","type":"https","ip_address":"10.11.12.138","port":"80"}'
Response:
{"id":"demo_service_2","token":"eyJldCI6IjEzNzk2NTIyNjEiLCJwYXNzd29yZCI6ImRiODUwZDMxZjYzNTQ4Njk2MzdhZDZiZThl\nMTQzODMxIiwidXNlciI6ImFkbWluIn0=\n"}
Example: Instant SSL Service
Request:
curl http://192.168.0.1:8000/restapi/v1/virtual_services -u 'eyJldCI6IjEzODAyODg0MTUiLCJwYXNzd29yZCI6ImJmYTdjMGFiODIzZjdkNTNlMzg2Y2E2YzRl\nZDlkNzM4IiwidXNlciI6ImFkbWluIn0=\n:' -X POST -H Content-Type:application/json -d '{"name": "instant_ssl", "ip_address": "10.11.25.233", "port": "445", "type":"instantssl", "address_version":"ipv4", "vsite":"default", "group":"default", "certificate":"cert", "service_hostname": "*"}'
Response:
{"id":"instant_ssl","token":"eyJldCI6IjEzODAzMDkzNDkiLCJwYXNzd29yZCI6ImQzOTI5MGZiMDBhNWE3MGY1MzU1NzNlNmU2\nMTQ5Mzc4IiwidXNlciI6ImFkbWluIn0=\n"}
To Retrieve Virtual Service
URL: /v1/virtual_services /v1/virtual_services/{virtual_service_id} | |||
Method: GET | |||
Description: Lists all virtual services if “service_id” is not specified. | |||
Parameter Name | Data Type | Mandatory | Description |
---|---|---|---|
Input Parameters: | |||
parameters | Alphanumeric | Optional | Any specific parameter name that needs to be retrieved. See Example 2. |
Example 1:
Request:
curl http://192.168.0.1:8000/restapi/v1/virtual_services/demo_service -u 'eyJldCI6IjEzODAyMzQyMzEiLCJwYXNzd29yZCI6IjAzNjU5ZGIxZDUwMzc3MTJlYzJhMDkzNTgy\nOGEwYTA2IiwidXNlciI6ImFkbWluIn0=\n:' -X GET
Response:
{"load_balance":{"algorithm":null,"persistence_method":"NONE"},"session_timeout":"60","comments":null,"group":"demo_vsite_group","ip_address":"10.11.15.176","id":"demo_service","token":"eyJldCI6IjEzODAyMzY3MDQiLCJwYXNzd29yZCI6ImQ1N2Q2MzM1OWU5YTYzYjAxN2YyOTdlMzZk\nYmEwZTYwIiwidXNlciI6ImFkbWluIn0=\n","ssl_offloading":{"ciphers":"default","trusted_certificates":[],"status":"0","enforce_client_certificate":"1","enable_tls_1_2":"1","enable_tls_1":"1","enable_sni":"0","enable_tls_1_1":"1","keepalive_requests":"64","enable_client_authentication":"0","enable_ssl_3":"1"},"enable":"1","name":"demo_service","enable_access_log":"1","port":"80","address_version":"ipv4","security":{"ignore_case":"1","trusted_hosts_action":"DEFAULT","mode":"PASSIVE","web_firewall_log_level":"5","web_firewall_policy":"default","rate_control_status":"OFF","trusted_hosts_group":null,"rate_control_pool":"NONE","client_ip_addr_header":null},"type":"HTTP","servers":[],"content_rules":[]}
Example 2:
Request:
curl http://192.168.0.1:8000/restapi/v1/virtual_services/demo_service -u 'eyJldCI6IjE1MDE4NDAxMTciLCJwYXNzd29yZCI6IjdhNDQyN2I1ODAxMGM2MTBiYWM5NGRiNGVj\nNTY3ZDFlIiwidXNlciI6ImFkbWluIn0=\n:' -X GET -G -d parameters=ip_address,load_balance,security
Response:
{"load_balance":{"algorithm":"round_robin","failover_method":"error","persistence_method":"none"},"security":{"ignore_case":"yes","trusted_hosts_action":"default","mode":"passive","web_firewall_log_level":"notice","web_firewall_policy":"sharepoint","rate_control_status":"off","trusted_hosts_group":"","rate_control_pool":"NONE","client_ip_addr_header":null},"ip_address":"99.99.116.7","id":"demo_service","token":"eyJldCI6IjE1MDQ0MDgwMTQiLCJwYXNzd29yZCI6ImJiZGE0MGNmY2I5ZjZjM2E1ZTFlN2M3ODI0\nYjk3NjE0IiwidXNlciI6ImFkbWluIn0=\n"}
To Update a Virtual Service
In this REST API call, the parameters can be passed in a Simple JSON request or a Nested JSON request based on the parameters that needs to be modified. For information on JSON requests, see Request Syntax.
URL: /v1/virtual_services/{virtual_service_id} | |||
Method: PUT | |||
Description: Updates the values of given parameters in the given service. | |||
Parameter Name | Data Type | Mandatory | Description |
---|---|---|---|
Input Parameters: | |||
ip_address | Numeric | Optional | The virtual IP address that will be used for accessing this application. |
port | Numeric | Optional | The port number on which your web server responds. |
certificate | Alphanumeric | Conditional | The certificate that needs to be presented to the browser when accessing this Service. Note: This is a required parameter ONLY when the service is HTTPS, Instant SSL, Custom SSL or FTP SSL |
service_hostname | Alphanumeric | Conditional | The domain name to identify and rewrite HTTP requests to HTTPS. Note: This is a required parameter ONLY when the service is Instant SSL. |
status | String | Optional | The status of the virtual service. The values include:
|
mask | Numeric | Optional | The netmask of the associated IP address. |
enable_access_logs | String | Optional | Specifies whether to log every request made to this Service or not. The values include:
|
session_timeout | Numeric | Optional | The time-out period in seconds for persistent connections with clients. Zero (0) indicates that the session never times out (session lives forever). |
comments | Alphanumeric | Optional | Description/comment for updating the parameter values. |
security.web_firewall_policy | Enumeration | Optional | A web firewall policy to be associated with the service. The enumerated values include:
|
security.web_firewall_log_level | Enumeration | Optional | The threshold for logging the error messages for the service. The enumerated values include:
|
security.mode | String | Optional | The mode to determine how the service responds to the offending traffic. The enumerated values include:
|
security. trusted_hosts_action | String | Optional | The action to be performed for a set of trusted hosts accessing the service. The values include:
|
security. trusted_hosts_group | String | Optional | The trusted hosts group to which the Trusted Hosts Action needs to be applied. Note: If you want to remove the associated trusted hosts group, pass the double inverted commas without space (“”) in the request. Example: {"security":{"trusted_hosts_group":""}} |
security.ignore_case | String | Optional | Determines how, for this service, the URLs are matched to rules like URL ACLs and URL Profiles. The values include:
|
security.client_ip_addr_header | Alphanumeric | Optional | The name of the header in which the client IP address is stored for identification by the server. |
security.rate_control_status | String | Optional | The rate control pool status. The enumerated values include:
|
security. rate_control_pool | String | Optional | The rate control pool to be associated with the service to limit the rate of requests. |
load_balance.algorithm | Enumeration | Optional | The algorithm to be used to distribute incoming requests for the service. The enumerated values include:
|
load_balance.persistence_idle_timeout | Numeric | Optional | The maximum idle time (in seconds) for a persistent connection. |
load_balance.persistence_method | Enumeration | Optional | The Persistence Method to be used to maintain the connection between a client and the first server that it connects to, even when the system is load balancing traffic. The enumerated values include:
|
load_balance.failover_method | Enumeration | Optional | The failover method to be used when responding to a request which is persistent, but the server that must serve the request is failed or set to "Out-of-Service". The enumerated values include:
|
load_balance. persistence_idle_timeout | Numeric | Optional | The maximum idle time (in seconds) for a persistent connection. A client is directed to the same Real Server unless the connection is inactive for more than the specified number of seconds. |
load_balance.source_ip_netmask | Numeric | Conditional | A subnet mask to make subsequent connections from clients, from the same subnet go to the same Real Server. Note: This is required ONLY when Persistence Method is source_ip. |
load_balance.persistence_cookie_name | Alphanumeric | Conditional | The name of the cookie that will be used for persistence. Note: This is required ONLY when Persistence Method is cookie_insert or cookie_passive. |
load_balance.persistence_cookie_domain | Alphanumeric | Optional | The domain name of the server of a persistency cookie. Note: This is required ONLY when Persistence Method is cookie_insert or cookie_passive. |
load_balance.persistence_cookie_path | URL | Optional | The path property of the persistency cookie. Note: This is required ONLY when Persistence Method is cookie_insert or cookie_passive. |
load_balance.cookie_age | Numeric | Conditional | The expiry age of the persistence cookie in minutes. |
load_balance.header_name | Alphanumeric | Conditional | The name of the header for which the value needs to be checked in the HTTP requests. Note: This is required ONLY when Persistence Method is http_header. |
load_balance.parameter_name | Alphanumeric | Conditional | The name of the parameter for which the value needs to be checked in the URL. Note: This is required ONLY when Persistence Method is url_parameter. |
ssl_offloading.status | String | Optional | The SSL status of the service. The values include:
|
ssl_offloading.certificate | Alphanumeric | Conditional | The certificate that needs to be presented to the client accessing the service. Note: This is required when SSL status is On. |
ssl_offloading.ecdsa_certificate | Alphanumeric | Optional | The ECDSA certificate that needs to be presented to the client accessing the service. |
ssl_offloading.enable_ssl_3 | String | Optional | SSL 3.0 protocol to be used by the clients to establish the connection to the service. The values include:
|
ssl_offloading.enable_tls_1 | String | Optional | TLS 1.0 protocol to be used by the clients to establish the connection to the service. The values include:
|
ssl_offloading.enable_tls_1_1 | String | Optional | TLS 1.1 protocol to be used by the clients to establish the connection to the service. The values include:
|
ssl_offloading.enable_tls_1_2 | String | Optional | TLS 1.2 protocol to be used by the clients to establish the connection to the service. The values include:
|
ssl_offloading.enable_sni | String | Optional | The status of Server Name Indication (SNI). The values include:
|
ssl_offloading.enable_strict_sni_check | String | Optional | Specifies whether to block access to non-SNI clients or not. The values include:
|
ssl_offloading.domain | Alphanumeric | Conditional | The domain name for which the SNI check needs to be enforced. You can specify multiple domain names with comma (,) as a delimiter without any space. Note:
|
ssl_offloading.sni_certificate | Alphanumeric | Conditional | The certificate(s) to be associated with the specified domain(s) name. This is a required parameter when enable_sni is set to Yes. |
ssl_offloading.sni_ecdsa_certificate | Alphanumeric | Optional | The ECDSA certificate to be associated with the specified domain(s) name. |
ssl_offloading.enable_pfs | String | Optional | Specifies whether to create a new ephemeral public-private key pair for every SSL/TLS session. The Values include:
|
ssl_offloading.ciphers | Enumeration | Optional | Specifies the ciphers to be used for the service. The enumerated values include:
For information on how to pass custom ciphers in a request, refer to the example given below ( see Example 2). |
ssl_offloading.selected_ciphers | String | Optional | The cipher suits to be used when ciphers is set to custom. Use comma (,) as a separator to specify multiple cipher suits. For information on how to pass custom ciphers in a request, refer to the example given below ( see Example 2). |
ssl_offloading.override_ciphers_ssl3 | String | Optional | The cipher suits to be used to override the default set of ciphers associated with the SSL.3.0 protocol. Note:
For information on how to pass override ciphers in a request, refer to the example given below ( see Example 3). |
ssl_offloading.override_ciphers_tls_1 | String | Optional | The cipher suits to be used to override the default set of ciphers associated with the TLS.1.0 protocol. Note:
For information on how to pass override ciphers in a request, refer to the example given below ( see Example 3). |
ssl_offloading.override_ciphers_tls_1_1 | String | Optional | The cipher suits to be used to override the default set of ciphers associated with the TLS.1.1 protocol. Note:
For information on how to pass override ciphers in a request, refer to the example given below ( see Example 3). |
ssl_offloading.enable_client_authentication | String | Optional | Specifies whether to enable or disable client authentication for the service, or the content rules configured under the service. The enumerated values include:
|
ssl_offloading.enforce_client_certificate | String | Conditional | Determines if the clients are required to present their certificate when connecting to the service. The values include:
Note:
|
ssl_offloading.client_authentication_rules | String | Conditional | The rules to which users must present their certificate when accessing the service. Note: This is applicable only when enable_client_authentication is set to for_selected_rule(s). |
ssl_offloading.trusted_certificates | String | Optional | The trusted certificate to be used to validate the certificates presented by the clients connecting to this service. |
instant_ssl. status | String | Optional | The status of instant SSL policy. The values include:
|
instant_ssl. secure_site_domain | Alphanumeric | Optional | The domain names for links embedded in a request. Sets which absolute URLs to rewrite in responses when Rewrite “status” is enabled; only URLs from these domain(s) are rewritten. Asterisk (*) means all inclusive. |
instant_ssl. sharepoint_rewrite_support | String | Optional | Specifies whether to provide support for SharePoint rewrite or not. Sharepoint rewrite support is relevant only if an Instant SSL service is created to protect a Microsoft SharePoint application. The values include:
|
advanced_configuration.enable_web_application_firewall | String | Optional | Specifies whether to enable or disable Web Application Firewall for this service. Note that Web Application Firewall globally manages network protection against attacks. By default, this is set to Yes. Select “no” if you want to temporarily disable Web Application Firewall without losing the configuration settings. The values include:
|
advanced_configuration.keepalive_requests | Numeric | Optional | The maximum number of requests allowed on a persistent HTTP connection. |
advanced_configuration.ntlm_ignore_extra_data | String | Optional | Specifies whether or not the Barracuda Web Application Firewall prematurely closes the TCP connection, when it receives a 401 error code from the Server, during the NTLM authentication process. The values include:
|
Example 1:
Request:
curl http://192.168.0.1:8000/restapi/v1/virtual_services/service1 -u 'eyJldCI6IjEzNzk2NzUwNTYiLCJwYXNzd29yZCI6IjA1MThjYWE1MWI3YWU3MTQxNjAxYzM2NzE5\nNTM2NTM0IiwidXNlciI6ImFkbWluIn0=\n:' -X PUT -H Content-Type:application/json -d '{"load_balance":{"failover_method":"ERROR"},"security":{"mode":"PASSIVE","web_firewall_policy":"sharepoint"},"ssl_offloading":{"enable_sni":yes,"enable_tls_1":yes}}'
Response:
{"id":"service1","token":"eyJldCI6IjE0NTY5OTc4NDUiLCJwYXNzd29yZCI6ImFjMjY2ZTMzNjU3N2I0Y2FlYTY5OWRlYWMx\nYzVmMmIzIiwidXNlciI6ImFkbWluIn0=\n"}
Example 2:
Request:
curl http://192.168.0.1:8000/restapi/v1/virtual_services/service1 -u 'eyJldCI6IjE0NTY5OTg4NTIiLCJwYXNzd29yZCI6IjQwODJlOTQyNjhhNjM0ZmUxOTg5Mjg1Yzg4\nMDJkNDExIiwidXNlciI6ImFkbWluIn0=\n:' -X PUT -H Content-Type:application/json -d '{"ssl_offloading":{"status":"on","enable_sni":"yes","enforce_client_certificate":"yes","certificate":"certificate1","domain":["yourdomain.com","brdomain.com"],"sni_certificate":["certificate1","Certificate10"],"sni_ecdsa_certificate":["Certificate2","Certificate3"],"trusted_certificates":["cert1"],"ciphers":"custom", "selected_ciphers":"AES256-GCM-SHA384,AES256-SHA256,AES256-SHA,CAMELLIA256-SHA,DES-CBC3-SHA,AES128-GCM-SHA256,AES128-SHA256,AES128-SHA,SEED-SHA,CAMELLIA128-SHA,RC4-SHA"}}'
Response:
{"id":"service1","token":"eyJldCI6IjE1MDQ1MTcxNDEiLCJwYXNzd29yZCI6ImU0ZWVjMzBjYTEyNjdiYzhkYWRlZDg5YWQx\nMmI0ODU2IiwidXNlciI6ImFkbWluIn0=\n"}
Example 3:
Request:
curl http://192.168.0.1:8000/restapi/v1/virtual_services/service1 -u 'eyJldCI6IjE0NTk0MDcxMzUiLCJwYXNzd29yZCI6ImJhMzYyZmM5NTQwMmMyZGNiMGI3NGE1NDZl\nNDYyYjZmIiwidXNlciI6ImFkbWluIn0=\n:' -X PUT -H Content-Type:application/json -d '{"ssl_offloading":{"override_ciphers_tls_1":"AES256-GCM-SHA384,AES256-SHA256,AES256-SHA,CAMELLIA256-SHA,DES-CBC3-SHA"}}'
Response:
{"id":"service1","token":"eyJldCI6IjE0NTk0MDczNjUiLCJwYXNzd29yZCI6ImU5M2MwMmJiNDZjODI3YjgzNzQ4ZWUxNmE4\nYmRkYTJiIiwidXNlciI6ImFkbWluIn0=\n"}
Examples for SSL Client Authentication
Example 1: To Disable Client Authentication
Request:
curl http://192.168.0.1:8000/restapi/v1/virtual_services/service -u 'eyJldCI6IjE0NTI2ODg5MzUiLCJwYXNzd29yZCI6ImY3NmYxODFmYTIyNTUwNDRiN2U1MDBhNDZk\nYWUxMjJkIiwidXNlciI6ImFkbWluIn0=\n:' -X PUT -H Content-Type:application/json -d '{"ssl_offloading":{"enable_client_authentication":"disable"}}'
Response:
{"id":"service","token":"eyJldCI6IjE0NTI2ODkxNDIiLCJwYXNzd29yZCI6ImQyZjI1MjUxOWM5NWU5NGQyMWI0YjA4Njk2\nNDZmYTk5IiwidXNlciI6ImFkbWluIn0=\n"}
Example 2: To Enable Client Authentication for a Service
Request:
curl http://192.168.0.1:8000/restapi/v1/virtual_services/service -u 'eyJldCI6IjE0NTI3NTE1MDgiLCJwYXNzd29yZCI6ImFiZjMxMTZiNTNiYjYzNzI0NzdkYWIyNzk1\nZmFkZDI1IiwidXNlciI6ImFkbWluIn0=\n:' -X PUT -H Content-Type:application/json -d '{"ssl_offloading":{"enable_client_authentication":"for_service","trusted_certificates":["trust"]}}'
Response:
{"id":"service","token":"eyJldCI6IjE0NTI3NTE3OTciLCJwYXNzd29yZCI6ImViMTRhZDM1YTQ1NWY4MjBhZDgzMzZjZTg2\nMmZlZDQ3IiwidXNlciI6ImFkbWluIn0=\n"}
Example 3: To Enable Client Authentication for Rule(s)
Request:
curl http://192.168.0.1:8000/restapi/v1/virtual_services/service -u 'eyJldCI6IjE0NTI3NTE1MDgiLCJwYXNzd29yZCI6ImFiZjMxMTZiNTNiYjYzNzI0NzdkYWIyNzk1\nZmFkZDI1IiwidXNlciI6ImFkbWluIn0=\n:' -X PUT -H Content-Type:application/json -d '{"ssl_offloading":{"enable_client_authentication":"for_selected_rule(s)","client_authentication_rules":["RG1"],"trusted_certificates":["trust"]}}'
Response:
{"id":"service","token":"eyJldCI6IjE0NTI3NTE4ODAiLCJwYXNzd29yZCI6ImEzN2FmNDE1NmU2OWNiZDNhMGRlYWZjNzcx\nYzRmZTljIiwidXNlciI6ImFkbWluIn0=\n"}
To Delete a Virtual Service
URL: /v1/virtual_services/{virtual_service_id} |
Method: DELETE |
Description: Deletes the given service. |
Example:
Request:
curl http://192.168.0.1:8000/restapi/v1/virtual_services/demo_service -u 'eyJldCI6IjEzODAyMzQyMzEiLCJwYXNzd29yZCI6IjAzNjU5ZGIxZDUwMzc3MTJlYzJhMDkzNTgy\nOGEwYTA2IiwidXNlciI6ImFkbWluIn0=\n:' -X DELETE
Response:
{"msg":"Successfully deleted","token":"eyJldCI6IjEzODAyMzcwMzEiLCJwYXNzd29yZCI6ImNkNjRjZDZjNTE5ZWQ4ZTFiZThkZjQ4YjNh\nYjE2MjI1IiwidXNlciI6ImFkbWluIn0=\n"}