Zevenet API v3.1 Reference
ZAPI (Zevenet Application Programming Interface) is the tool for system administrator to controler Zevenet load balancer conduct.
It is necessary active the zapi user from the web interface before use it, System/Users.
Once the zapi user has been created, it is possible send request to the URL, https://(zevenet_server):444/zapi/v3.1/zapi.cgi/(URI_path), where zevenet_server is the IP where HTTP service is listening.
URI_path defines the object or action to act. His behavior and his parameters will be defined within each one doctumentation section.
The verbs used in this API will be GET, POST, PUT or DELETE. A PUT or POST request always need almost a parameter although this doesn’t need any required parameter.
Certificates
Zevenet supports cetificates in PEM format to use them with your HTTP farms with HTTPS listener. If you want to learn more about how to create pem certificates please visit the following article: GENERATE CERTIFICATES IN PEM FORMAT
List all Certificates
List all Certificates
Request example:
curl -k -X GET -H "ZAPI_KEY: <ZAPI_KEY_STRING>"
https://<zevenet_server>:444/zapi/v3.1/zapi.cgi/certificates
GET /certificates
List all CSR and PEM certificates in the certificates store, those certificates can be used with HTTPS farms.
The response will be a JSON object with a key set to params. The value of this will be an array of certificate objects, each of which contain the key attributes below.
Response example:
{
"description" : "List all certificates",
"params" : [
{
"CN" : "Zen Load Balancer",
"creation" : "Jan 12 14:49:03 2011 GMT",
"expiration" : "Jan 9 14:49:03 2021 GMT",
"file" : "zencert.pem",
"issuer" : "Zen Load Balancer",
"type" : "Certificate"
}
]
}
Response parameters
| Field | Type | Description |
|---|---|---|
| params | Object[ ] | List of certificate objects. |
Certificate Object
| Field | Type | Description |
|---|---|---|
| CN | String | Domain common name. |
| creation | String | Creation date. |
| expiration | String | Expiration date. |
| file | String | File name of the certificate, unique ID. |
| issuer | String | Certified Authority signing the certificate. |
| type | String | CSR or Certificate. |
Download Certificate
Download Certificate
Request example:
curl -k -X GET -H "ZAPI_KEY: <ZAPI_KEY_STRING>"
https://<zevenet_server>:444/zapi/v3.1/zapi.cgi/certificates/example.pem
GET /certificates/<file>
Download a certificate installed in the certificates store, use the file name in the request to identify it.
The response will include the headers indicated below with information about the file. The body of the response will be the content of the file.
Response headers:
HTTP/1.1 200 OK
Date: Thu, 22 Dec 2016 09:27:47 GMT
Content-Disposition: attachment; filename="example.pem"
Content-Type: application/x-download; charset=ISO-8859-1
Content-Length: 2359
Show Certificate details
Show Certificate details
Request example:
curl -k -X GET -H "ZAPI_KEY: <ZAPI_KEY_STRING>"
https://<zevenet_server>:444/zapi/v3.1/zapi.cgi/certificates/example.pem/info
GET /certificates/<file>/info
Show all the information included in a given certificate in the certificates store, including signatures, it is required the file name to make reference.
Response example:
Certificate:
Data:
Version: 3 (0x2)
Serial Number: 14346016480403539444 (0xc71749fb005a45f4)
Signature Algorithm: sha1WithRSAEncryption
Issuer: C=ES, ST=Spain, L=Spain, O=Sofintel, OU=Telecommunications, CN=Zen Load Balancer/emailAddress=zenloadbalancer-support@lists.sourceforge.net
Validity
Not Before: Jan 12 14:49:03 2011 GMT
Not After : Jan 9 14:49:03 2021 GMT
Subject: C=ES, ST=Spain, L=Spain, O=Sofintel, OU=Telecommunications, CN=Zen Load Balancer/emailAddress=zenloadbalancer-support@lists.sourceforge.net
Subject Public Key Info:
Public Key Algorithm: rsaEncryption
Public-Key: (1024 bit)
Modulus:
...
Show activation Certificate details
Show activation Certificate details
Request example:
curl -k -X GET -H "ZAPI_KEY: <ZAPI_KEY_STRING>"
https://<zevenet_server>:444/zapi/v3.1/zapi.cgi/certificates/activation
GET /certificates/activation
Show all the information included in the activation certificate, including signatures, this certificate is saved in the certificates store. If the activation certificate is deleted then the product will be deactivated.
Delete a Certificate
Delete a Certificate
Request example:
curl -k -X DELETE -H "ZAPI_KEY: <ZAPI_KEY_STRING>"
https://<zevenet_server>:444/zapi/v3.1/zapi.cgi/certificates/example.pem
DELETE /certificates/<file>
Delete a certificate by file name in the certificates store.
Response example:
{
"description" : "Delete certificate",
"message" : "The Certificate example.pem has been deleted.",
"success" : "true"
}
Delete the activation Certificate
Delete the activation Certificate
Request example:
curl -k -X DELETE -H "ZAPI_KEY: <ZAPI_KEY_STRING>"
https://<zevenet_server>:444/zapi/v3.1/zapi.cgi/certificates/activation
DELETE /certificates/activation
Delete the activation certificate installed in the certificates store. If this certificate is deleted then the Load Balancer is deactivated.
Response example:
{
"description" : "Delete activation certificate",
"message" : "The activation certificate has been deleted",
"success" : "true"
}
Create a CSR certificate
Create a CSR certificate
Request example:
curl -k -X POST -H "ZAPI_KEY: <ZAPI_KEY_STRING>" -H 'Content-Type: application/json'
-d '{"name":"NewCSR","fqdn":"host.domain.com","division":"IT","organization":"Example Corp.",
"locality":"Madrid","state":"Madrid","country":"ES","mail":"info@domain.com"}'
https://<zevenet_server>:444/zapi/v3.1/zapi.cgi/certificates
POST /certificates
Create a Certificate Signing Request (CSR file).
Request parameters
| Field | Type | Description | Required |
|---|---|---|---|
| name | String | Certificate ID name. | true |
| fqdn | String | The fully qualified domain name of your server. | true |
| division | String | The division of your organization handling the certificate. | true |
| organization | String | The legal name of your organization. | true |
| locality | String | The city where your organization is located. | true |
| state | String | The state/region where your organization is located. | true |
| country | String | The two-letter ISO code for the country where your organization is location. | true |
| String | An email address used to contact your organization. | true |
Response example:
{
"description" : "Create CSR",
"message" : "Certificate NewCSR created",
"success" : "true"
}
Upload a Certificate
Upload a Certificate
Request example:
curl -k -X POST -H "ZAPI_KEY: <ZAPI_KEY_STRING>" -H 'Content-Type: text/plain'
--tcp-nodelay --data-binary @/local_path/to/example.pem
https://<zevenet_server>:444/zapi/v3.1/zapi.cgi/certificates/example.pem
POST /certificates/<file>
Upload a PEM certificate for HTTP farms with HTTPS listener.
Requires the parameter --tcp-nodelay, and --data-binary to upload the file in binary mode.
Request URI parameters
| Field | Type | Description | Required |
|---|---|---|---|
| file | String | Certificate file name to upload and save in the certificates store. | true |
Response example:
{
"description" : "Upload PEM certificate",
"message" : "Certificate uploaded",
"success" : "true"
}
Upload an activation Certificate
Upload an activation Certificate
Request example:
curl -k -X POST -H "ZAPI_KEY: <ZAPI_KEY_STRING>" -H 'Content-Type: text/plain'
--tcp-nodelay --data-binary @/path/to/example.pem
https://<zevenet_server>:444/zapi/v3.1/zapi.cgi/certificates/activation
POST /certificates/activation
Upload an activation certificate with PEM format, this certificate is needed to enable all functionalities. This certificate is saved in the certificates store, if the activation certificate exists in the certificates store then the previous certificate is overwriten.
Response example:
{
"description" : "Upload activation certificate",
"message" : "Activation certificate uploaded",
"success" : "true"
}
List Ciphers
List Ciphers
Request example:
curl -k -X GET -H "ZAPI_KEY: <ZAPI_KEY_STRING>"
https://<zevenet_server>:444/zapi/v3.1/zapi.cgi/ciphers
GET /ciphers
List the available ciphers that a HTTPS farm can use.
The SSL offloading chiper will be available only if it is supported by the processor.
The response will be a JSON object with a key set to params. The value of this will be an array of certificate objects, each of which contain the key attributes below.
Response example:
{
"description" : "Get the ciphers available",
"params" : [
{
"ciphers" : "all",
"description" : "All"
},
{
"ciphers" : "highsecurity",
"description" : "High security"
},
{
"ciphers" : "customsecurity",
"description" : "Custom security"
},
{
"ciphers" : "ssloffloading",
"description" : "SSL offloading"
}
]
}
Response parameters
| Field | Type | Description |
|---|---|---|
| params | Object[ ] | List of certificate objects. |
Certificate Object
| Field | Type | Description |
|---|---|---|
| ciphers | String | It is used as unique identifier. |
| description | String | Friendly name. |
Farms
Zevenet is able to manage traffic in three different ways, each way is managed by a different module, Local service load balancer or LSLB module, Global Service Load Balancer or GSLB module and Datalink Service Load Balancer or DSLB module.
All modules work with the Farm profile concept, a Farm profile is a group of parameters ready to do an especific action with the network traffic, it is important to understand what is able to do each farm profile in order to obtain the best results of Zevenet ADC.
- LSLB: This module is able to work with http and l4xnat profile farms. It works as a web reverse proxy or router
- GSLB: This module is able to work with gslb profile farm. It works as Domain Name Server
- DSLB: This module is able to work with datalink profile farm. It works as a gateway.
List all farms
List all farms
Request example:
curl -k -X GET -H "ZAPI_KEY: <ZAPI_KEY_STRING>"
https://<zevenet_server>:444/zapi/v3.1/zapi.cgi/farms
GET /farms
List all available farms
The response will be a JSON object with a key set to params. The value of this will be an array of farm resume objects, each of which contains the key attributes below.
Farm Object
| Field | Type | Description |
|---|---|---|
| farmname | String | Farm descriptive name. It is used as unique identificator. |
| profile | String | Profile type, the profile available values are: http, https or l4xnat for LSLB module, gslb for GLSB module and datalink for DSLB module |
| status | String | Farm status. The available status values are: down, the farm is not running; needed restart, the farm is up but it is pending of a restart action; critical, the farm is up and all backends are unreachable or maintenance; problem, the farm is up and there are some backend unreachable, but almost a backend is in up status; maintenance, the farm is up and there are backends in up status, but almost a backend is in maintenance mode; up, the farm is up and all the backends are working success. |
| vip | String | Virtual IP where farm is receiving traffic |
| vport | String | Virtual Port where farm is receiving traffic, port available values are: a port number for http[s], l4xnat and gslb profiles, a group of ports separated by “,” or a port range separated by “:” for l4xnat profiles, in l4xnat both separator values (“,” and “:”) can be used at the same field. |
Response example:
{
"description" : "List farms",
"params" : [
{
"farmname" : "httpFarm",
"profile" : "http",
"status" : "up",
"vip" : "192.168.101.146",
"vport" : "81"
}
]
}
Delete a Farm
Delete a Farm
Request example:
curl --tlsv1 -k -X DELETE -H 'Content-Type: application/json' -H "ZAPI_KEY: <ZAPI_KEY_STRING>"
https://<zevenet_server>:444/zapi/v3.1/zapi.cgi/farms/FarmHTTP
DELETE /farms/<farmname>
Delete a farm through its farm name identfier.
Response example:
{
"description" : "Delete farm FarmHTTP",
"message" : "The Farm FarmHTTP has been deleted.",
"success" : "true"
}
Set an action in a Farm
Set an action in a Farm
Request example:
curl -k -X PUT -H 'Content-Type: application/json' -H "ZAPI_KEY: <ZAPI_KEY_STRING>"
-d '{"action":"stop"}' https://<zevenet_server>:444/zapi/v3.1/zapi.cgi/farms/FarmTCP/actions
PUT /farms/<farmname>/actions
Apply an action to a farm, see the Request parameters table for actions.
Request parameters
| Field | Type | Description |
|---|---|---|
| action | String | Set the action desired. The actions are: stop, the farm will be stopped. start, the farm will be started and restart, the farm will be stopped and started automatically. |
Response example:
{
"description" : "Set a new action in FarmHTTP",
"params" : [
{
"action" : "stop"
}
]
}
Response parameters
If there are no issues in the configuration then zapi will return the requested action.
HTTP Farms
HTTP profile is an advanced layer 7 load balancing (or Application Delivery Controller) with proxy special properties. This profile offers some features like HTTPS layer 7 load balancing combinated with SSL offload acceleration. This profile is adecuated for web services (web application servers included) and all application protocols based on HTTP and HTTPS protocols like WebDav, RDP over HTTP, ICA over HTTP, etc. In order to configure this farm profile, a virtual IP address and a virtual TCP port will be required.
Retrieve farm by name
Retrieve farm by name
Request example:
curl -k -X GET -H "ZAPI_KEY: <ZAPI_KEY_STRING>"
https://<zevenet_server>:444/zapi/v3.1/zapi.cgi/farms/httpFarm
GET /farms/<farmname>
Show all configuration about a given farm.
Response example:
{
"description" : "List farm httpFarm",
"ipds" : {
"blacklists" : [
"rem"
],
"dos" : [],
"rbl" : [
"protection_ssh"
]
},
"params" : {
"certlist" : [
{
"file" : "zencert.pem",
"id" : 1
}
],
"cipherc" : "ALL",
"ciphers" : "all",
"contimeout" : 20,
"disable_sslv2" : "true",
"disable_sslv3" : "false",
"disable_tlsv1" : "false",
"disable_tlsv1_1" : "true",
"disable_tlsv1_2" : "false",
"error414" : "Request URI is too long.",
"error500" : "An internal server error occurred. Please try again later.",
"error501" : "This method may not be used.",
"error503" : "The service is not available. Please try again later.",
"httpverb" : "MSRPCext",
"ignore_100_continue" : "true",
"listener" : "https",
"reqtimeout" : 30,
"restimeout" : 45,
"resurrectime" : 10,
"rewritelocation" : "enabled",
"status" : "up",
"vip" : "192.168.100.211",
"vport" : 200
},
"services" : [
{
"backends" : [],
"cookiedomain" : "",
"cookieinsert" : "false",
"cookiename" : "",
"cookiepath" : "",
"cookiettl" : 0,
"fgenabled" : "false",
"fglog" : "false",
"fgscript" : "",
"fgtimecheck" : 5,
"httpsb" : "false",
"id" : "service3",
"leastresp" : "false",
"persistence" : "",
"redirect" : "",
"redirecttype" : "",
"sessionid" : "",
"ttl" : 0,
"urlp" : "",
"vhost" : ""
},
{
"backends" : [
{
"id" : 0,
"ip" : "192.168.0.168",
"port" : 80,
"status" : "up",
"timeout" : null,
"weight" : null
}
],
"cookiedomain" : "",
"cookieinsert" : "false",
"cookiename" : "",
"cookiepath" : "",
"cookiettl" : 0,
"fgenabled" : "false",
"fglog" : "false",
"fgscript" : "tcp_check",
"fgtimecheck" : 5,
"httpsb" : "false",
"id" : "srv",
"leastresp" : "false",
"persistence" : "",
"redirect" : "",
"redirecttype" : "",
"sessionid" : "",
"ttl" : 0,
"urlp" : "",
"vhost" : ""
},
]
}
Response parameters
The response will be a JSON object with the format below.
Farm Object:
| Field | Type | Description |
|---|---|---|
| ipds | Object | List of IPDS rules applied to this farm. |
| params | Object | Parameters of farm configuration. |
| services | Object[] | Array with all services created in this farm and its configuration. |
IPDS Object:
| Field | Type | Description |
|---|---|---|
| blacklists | String[] | Blacklist rules applied to the farm. |
| dos | String[] | DoS rules applied to the farm. |
| rbl | String[] | RBL rules applied to the farm. |
Parameters object for HTTP farms:
| Field | Type | Description |
|---|---|---|
| certlist | Object[] | Only in https profile. Certificates list actived in the farm, in pem format, it is allowed to add more than one pem certificate to the same farm for SNI support. listener with https value is required. Any certificate in the certificates store can be used here. |
| cipherc | String | Only in https listener. This is the allowed customized list of ciphers that will be accepted by the SSL connection, which it’s a string in the same format as in OpenSSL ciphers. This atribute is used only when ciphers field has the value sutomsecurity. |
| ciphers | String | Only in listener with https value. Used to build a list of ciphers accepted by SSL connections in order to harden the SSL connection. The options are: all, all the ciphers will be accepted; highsecurity, only ciphers for high security will be accepted; customsecurity, only ciphers loaded in cipherc field will be accepted; or ssloffloading, it devolves the encrypting job to the process, this cipher depends on the processor. |
| contimeout | Number | How long the farm is going to wait for a TCP connection to the backend in seconds. |
| disable_sslv2 | String | Only in https listener. If this field has the value true the connections using SSL security protocol with version 2 is not allowed; or false if the protocol SSLv2 is allowed. |
| disable_sslv3 | String | Only in https listener. If this field has the value true the connections using SSL security protocol with version 3 is not allowed; or false if the protocol SSLv3 is allowed. |
| disable_tlsv1 | String | Only in https listener. If this field has the value true the connections using TLS security protocol with version 1 is not allowed; or false if the protocol TLSv1 is allowed. |
| disable_tlsv1_1 | String | Only in https listener. If this field has the value true the connections using TLS security protocol with version 1.1 is not allowed; or false if the protocol TLSv1.1 is allowed. |
| disable_tlsv1_2 | String | Only in https listener. If this field has the value true the connections using TLS security protocol with version 1.2 is not allowed; or false if the protocol TLSv1.2 is allowed. |
| error414 | String | Personalized message for responsing with the 414 HTTP error code. |
| error500 | String | Personalized message for responsing with the 500 HTTP error code. |
| error501 | String | Personalized message for responsing with the 501 HTTP error code. |
| error503 | String | Personalized message for responsing with the 503 HTTP error code. |
| httpverb | String | This field indicates the operations that will be permitted to the HTTP client requests. available values are: standardHTTP,accepted http requests GET, POST, HEAD. extendedHTTP, accepted previous http requests plus PUT,DELETE. standardWebDAV, accepted previous http requests plus LOCK, UNLOCK, PROPFIND, PROPPATCH, SEARCH, MKCOL, MOVE, COPY, OPTIONS, TRACE, MKACTIVITY, CHECKOUT, MERGE, REPORT, MSextWebDAV accepted previous http requests plus SUBSCRIBE, UNSUBSCRIBE, NOTIFY, BPROPFIND, BPROPPATCH, POLL, BMOVE, BCOPY, BDELETE, CONNECT, or MSRPCext, accepted previous http requests plus RPC_IN_DATA, RPC_OUT_DATA. Note that those values are case-sensitve. |
| ignore_100_continue | String | If this field has the value true the 100 continue HTTP heade will be ignored; if the value is false, the 100 continue header will be process. |
| listener | String | A listener defines how the farm is going to play with the requests from the clients. The options are: http for not secured protocol or https for secured protocol. |
| reqtimeout | Number | How long the farm is going to wait for a client request in seconds. |
| restimeout | Number | How long the farm is going to wait for a response from the backends in seconds. |
| resurrectime | Number | The period to get out a fallen real server, after this period the load balancer checks if the real server is alive, in seconds. |
| rewritelocation | String | If it is enabled, the farm is forced to modify the Location: and Content-location: headers in responses to clients with the virtual host. The options are: enabled, actived disabled, inactived or enabled-backends only the backend address is compared. |
| status | String | Farm status. The available status values are: down, the farm is not running; needed restart, the farm is up but it is pending of a restart action; critical, the farm is up and all backends are unreachable or maintenance; problem, the farm is up and there are some backend unreachable, but almost a backend is in up status; maintenance, the farm is up and there are backends in up status, but almost a backend is in maintenance mode; up, the farm is up and all the backends are working success. |
| vip | String | IP of the farm, where the virtual service is listening. |
| vport | Number | Port of the farm, where the virtual service is listening. |
Certlist Object:
| Field | Type | Description |
|---|---|---|
| file | String | The certificate name, references to the certificate in the certificates store. |
| id | Number | Certificate ID, The order in the list, first one will be the used by default if virtual host header doesn’t match with CN field in the certificate. Used for SNI. |
Services object for HTTP farms:
| Field | Type | Description |
|---|---|---|
| backends | Object[] | Backends defined in the service. |
| cookiedomain | String | Cookie insertion will be executed if domain matches in the cookie content. Enable cookieinsert field is required. |
| cookieinsert | String | It enables the cookie insertion for backends sticky sessions. The options are true, the profile will search the given cookie in field cookiename, if it doesn’t exist then this cookie will be added, false, not action is taken. |
| cookiename | String | The cookie name (session ID) will be used for identifying the sticky process to backends. Enable cookieinsert field is required. |
| cookiepath | String | It manages the cookie path value for the given cookie. Enable cookieinsert field is required. |
| cookiettl | Number | It is the max time of life for a cookie, in seconds. Enable cookieinsert field is required. |
| fgenabled | String | Enable the use of farm guardian. true farm guardian is enabled and checking backends status, false farm guardian is disabled and not checking backends status. In HTTP profiles a check_tcp is executed by default even if farm guardian is disabled. |
| fglog | String | Enable the use of logs in farm guardian. true enabled, false, disabled. fgenabled is required. |
| fgscript | String | The command that farm guardian will use for checking backends health. true enabled, false, disabled. fgenabled is required. |
| fgtimecheck | Number | farm guardian will check each ‘timetocheck’ seconds the backend health status. fgenabled is required. |
| httpsb | String | This parameter indicates to the farm that the backends servers defined in the current service are using the HTTPS language and then the data will be encrypted before to be sent. true, the profile sends the traffic in HTTPS protocol to the backends, false, the profile sends the traffic in HTTP protocol to the backends. |
| id | String | Service’s name, it can’t be modified once the service is created. |
| leastresp | String | It enables the least responde balancing method. true frecuently the profile checks which backend is taking less time to respond in order to send more connections to this one, false profile doesn’t check which backend is taking less time to respond. |
| persistence | String | This parameter defines how the HTTP service is going to manage the client session. The options are: “” empty string, no action is taken, IP the persistence session is done in base of client IP, BASIC the persistence session is done in base of BASIC headers, URL the persistence session is done in base of a field in the URI, PARM the persistence session is done in base of a value at the end of the URI, COOKIE the persistence session is done in base of a cookie name, this cookie has to be created by the backends, and HEADER, the persistence session is done in base of a Header name. |
| redirect | String | It behaves as a special backend, as the client request is answered by a redirect to a new URL automatically. If redirect is configured then the request will not be forwarded to the backend, a Redirect will be responded to the client instead. |
| redirecttype | String | How the redirection will be done, two options: default, the url is taken as an absolute host and path to redirect to, append, the original request path or URI will be appended to the host and path you specified with default option. If redirect field is not configurated, this field will be an empty string. |
| sessionid | String | It is avaliable if persistence field is URL, COOKIE or HEADER, the parameter value will be searched by the farm in the http header and will manage the client session. |
| ttl | Number | Only with persistence. This value indicates the max time of life for an inactive client session (max session age) in seconds. |
| urlp | String | Allows to determine a web service regarding the URL the client is requesting through a specific URL pattern which will be syntactically checked. PCRE regular expression is supported. |
| vhost | String | It specifies the condition determined by the domain name through the same virtual IP and port defined by a HTTP farm. PCRE regular expression is supported. |
Backend object for HTTP farms:
| Field | Type | Description |
|---|---|---|
| id | Number | Backend identifier inside the given service. |
| ip | String | Backend’s IP where the real service is running. |
| port | Number | Backend’s port where the real service is running. |
| status | String | Backend status. The possible values are: up, the farm is running and the backend is ready to receive connections; down, the farm is running and the service has detected that the backend is not working; maintenance, backend is marked as not ready for receiving connections by the administrator, this option is useful for backend’s maintance tasks; undefined, the backend status has been not checked. |
| timeout | Number | It’s the backend timeout to respond a certain request, in seconds. If null system will use global parameter Backends timeout. |
| weight | Number | It’s the weight value for the current real server, backend with higher weight value will receive more connections. Default value null, not special weight used for this backend. |
Create a new Farm
Create a new Farm
Request example:
curl -k -X POST -H 'Content-Type: application/json' -H "ZAPI_KEY: <ZAPI_KEY_STRING>"
-d '{"farmname":"newHTTPfarm", "profile":"http", "vip":"192.168.100.23",
"vport":80}' https://<zevenet_server>:444/zapi/v3.1/zapi.cgi/farms
POST /farms
Create a new HTTP farm.
Request parameters
| Field | Type | Description | Required |
|---|---|---|---|
| farmname | String | Farm descriptive name. It is used as unique identifier. | true |
| profile | String | The profile of the created Farm. For http farms is http. | true |
| vip | String | IP of the farm, where the virtual service is going to run. The indicated IP must be configured in the system and UP | true |
| vport | Number | Port of the farm, where the virtual service is going to listen. Same virtual port and virtual IP must not be in use by another farm. | true |
Response example:
{
"description" : "Creating farm 'newHTTPfarm'",
"params" : {
"interface" : "eth0.2",
"farmname" : "newHTTPfarm",
"profile" : "http",
"vip" : "192.168.100.23",
"vport" : 80
}
}
Response parameters
The response will be a json with all requested values updated. See response example for more information.
Modify a Farm
Modify a Farm
Request example:
curl -k -X PUT -H 'Content-Type: application/json' -H "ZAPI_KEY: <ZAPI_KEY_STRING>"
-d '{"contimeout":22,"newfarmname":"FarmHTTP2","vip":"178.62.126.152","vport":88,"ignore_100_continue":"true",
"restimeout":47,"resurrectime":12,"reqtimeout":32,"rewritelocation":"enabled","httpverb":"standardHTTP",
"error414":"Message error 414","error500":"Message error 500","error501":"Message error 501",
"error503":"Message error 503","listener":"https","ciphers":"customsecurity","disable_sslv2":"true",
"disable_sslv3":"false","disable_tlsv1":"false","disable_tlsv1_1":"true","disable_tlsv1_2":"false",
"cipherc":"TLSv1+SSLv3+HIGH:-MEDIUM:-LOW*:-ADH*"}' https://<zenlb_server>:444/zapi/v3.1/zapi.cgi/farms/FarmHTTP
PUT /farms/<farmname>
Modify global parameters for a given HTTP farm.
Request parameters
| Field | Type | Description |
|---|---|---|
| contimeout | Number | How long the farm is going to wait for a connection to the backend in seconds. |
| restimeout | Number | How long the farm is going to wait for a response from the backends in seconds. |
| resurrectime | Number | This value in seconds is the period to get out a blacklisted backend and checks if is alive. |
| reqtimeout | Number | How long the farm is going to wait for a client request in seconds. |
| disable_sslv2 | String | Only in https listener. If this field has the value true the connections using SSL security protocol with version 2 is not allowed; or false if the protocol SSLv2 is allowed. |
| disable_sslv3 | String | Only in https listener. If this field has the value true the connections using SSL security protocol with version 3 is not allowed; or false if the protocol SSLv3 is allowed. |
| disable_tlsv1 | String | Only in https listener. If this field has the value true the connections using TLS security protocol with version 1 is not allowed; or false if the protocol TLSv1 is allowed. |
| disable_tlsv1_1 | String | Only in https listener. If this field has the value true the connections using TLS security protocol with version 1.1 is not allowed; or false if the protocol TLSv1.1 is allowed. |
| disable_tlsv1_2 | String | Only in https listener. If this field has the value true the connections using TLS security protocol with version 1.2 is not allowed; or false if the |
| rewritelocation | String | If it is enabled, the farm is forced to modify the Location: and Content-location: headers in responses to clients with the virtual host. The options are: enabled, actived disabled, inactived or enabled-backends only the backend address is compared. |
| httpverb | String | This field indicates the operations that will be permitted to the HTTP client requests. available values are: standardHTTP,accepted http requests GET, POST, HEAD. extendedHTTP, accepted previous http requests plus PUT,DELETE. standardWebDAV, accepted previous http requests plus LOCK, UNLOCK, PROPFIND, PROPPATCH, SEARCH, MKCOL, MOVE, COPY, OPTIONS, TRACE, MKACTIVITY, CHECKOUT, MERGE, REPORT, MSextWebDAV accepted previous http requests plus SUBSCRIBE, UNSUBSCRIBE, NOTIFY, BPROPFIND, BPROPPATCH, POLL, BMOVE, BCOPY, BDELETE, CONNECT, or MSRPCext, accepted previous http requests plus RPC_IN_DATA, RPC_OUT_DATA. Note that those values are case-sensitve. |
| ignore_100_continue | String | If this field has the value true the 100 continue HTTP heade will be ignored; if the value is false, the 100 continue header will be process. |
| error414 | String | Personalized message error 414. |
| error500 | String | Personalized message error 500. |
| error501 | String | Personalized message error 501. |
| error503 | String | Personalized message error 503. |
| listener | String | A listener defines how the farm is going to play with the requests from the clients. The options are: http for not secured protocol or https for secured protocol. |
| ciphers | String | Only in listener with https value. Used to build a list of ciphers accepted by SSL connections in order to harden the SSL connection. The options are: all, all the ciphers will be accepted; highsecurity, only ciphers for high security will be accepted; customsecurity, only ciphers loaded in cipherc field will be accepted; or ssloffloading, it devolves the encrypting job to the process, this cipher depends on the processor. |
| cipherc | String | Only in https listener. This is the allowed customized list of ciphers that will be accepted by the SSL connection, which it’s a string in the same format as in OpenSSL ciphers. This atribute is used only when ciphers field has the value sutomsecurity. |
| newfarmname | String | The new Farm’s name. Farm must be stopped. |
| vport | Number | Port of the farm, where the virtual service is listening. |
| vip | String | IP of the farm, where the virtual service is listening, this IP must be configured and up in the system. |
Response example:
{
"description" : "Modify farm FarmHTTP",
"params" : {
"cipherc" : "TLSv1+SSLv3+HIGH:-MEDIUM:-LOW*:-ADH*",
"ciphers" : "customsecurity",
"contimeout" : 22,
"disable_sslv2" : "true",
"disable_sslv3" : "false",
"disable_tlsv1" : "false",
"disable_tlsv1_1" : "true",
"disable_tlsv1_2" : "false",
"error414" : "Message error 414",
"error500" : "Message error 500",
"error501" : "Message error 501",
"error503" : "Message error 503",
"httpverb" : "standardHTTP",
"ignore_100_continue" : "true",
"listener" : "https",
"newfarmname" : "FarmHTTP",
"reqtimeout" : 32,
"restimeout" : 47,
"resurrectime" : 12,
"rewritelocation" : "enabled",
"vip" : "178.62.126.152",
"vport" : 88
}
}
Response parameters
The response will be a json with all requested values updated. See response example for more information.
Add a Certificate
Add a Certificate
Request example:
curl -k -X POST -H 'Content-Type: application/json' -H "ZAPI_KEY: <ZAPI_KEY_STRING>"
-d '{"file":"example.pem"}' https://<zevenet_server>:444/zapi/v3.1/zapi.cgi/farms/httpFarm/certificates
POST /farms/<farmname>/certificates
Include an available PEM Certificate to the SNI list or certlist array of an HTTP farm with an HTTPS listener. The used certificate has to be already uploaded in the system, see Certificates > List all Certificates for the available certificates list.
Request parameters
| Field | Type | Description | Required |
|---|---|---|---|
| file | String | certificate file name, previously the certificate has to be uploaded in the system. | true |
Response example:
{
"description" : "Add certificate",
"message" : "The certificate example.pem has been added to the SNI list of farm httpFarm, you need restart the farm to apply",
"success" : "true",
"status": "needed restart"
}
Delete a Certificate
Delete a Certificate
Request example:
curl -k -X DELETE -H "ZAPI_KEY: <ZAPI_KEY_STRING>"
https://<zevenet_server>:444/zapi/v3.1/zapi.cgi/farms/MyHttpFarm/certificates/example.pem
DELETE /farms/<farmname>/certificates/<file>
Delete the certificate with the selected file name from the certlist in the HTTP farm with HTTPS listener. The certificate will not be deleted of the certificates store.
Response example:
{
"description" : "Delete farm certificate",
"message" : "The Certificate example.pem has been deleted.",
"success" : "true",
"status": "needed restart"
}
Add an IPDS rule
Add an IPDS rule
Request example:
curl -k -X POST -H 'Content-Type: application/json' -H "ZAPI_KEY: <ZAPI_KEY_STRING>"
-d '{"name":"china"}' https://<zevenet_server>:444/zapi/v3.1/zapi.cgi/farms/httpFarm/ipds/blacklists
POST /farms/<farmname>/ipds/<dos|blacklists|rbl>
Apply a blacklist, DoS or RBL rule to the farm.
Request parameters
| Field | Type | Description |
|---|---|---|
| name | String | IPDS rule name used as unique identifier. |
Response example:
{
"description" : "Apply a rule to a farm",
"message" : "Blacklist rule china was applied successful to the farm httpFarm.",
"success" : "true"
}
Remove an IPDS rule
Remove an IPDS rule
Request example:
curl -k -X DELETE -H "ZAPI_KEY: <ZAPI_KEY_STRING>"
https://<zevenet_server>:444/zapi/v3.1/zapi.cgi/farms/httpFarm/ipds/blacklists/china
DELETE /farms/<farmname>/ipds/<dos|blacklists|rbl>/<name>
Remove a blacklist, DoS or RBL rule from a given farm using its idenficator name.
Response example:
{
"description" : "Delete a rule form a farm",
"message" : "Blacklist rule china was removed successful from the farm httpFarm.",
"success" : "true"
}
HTTP - Services
The services within a HTTP profile farm provides a content switching method to deliver several web services with different properties, backends or even persistence methods, through some deterministic conditions used by the farm core in order to match the correct service for every client request. This service definition will be used by the farm in order to determine the backends servers that could deliver the response to the client.
Inside service object there are two kinds of values: service related and farmguardian related.
Farmguardian is used for advanced monitoring state of backends and totally personalized for your own scripts for the current service. When a problem is detected by farmguardian automatically disables the real server and will be marked as blacklisted.
Retrieve service by ID
Retrieve service by ID
Request example:
curl -k -X GET -H "ZAPI_KEY: <ZAPI_KEY_STRING>"
https://<zevenet_server>:444/zapi/v3.1/zapi.cgi/farms/cookiefarm/services/serv
GET /farms/<farmname>/services/<id>
Show all configuration about a given service.
Response example:
{
"description" : "Get services of a farm",
"services" : {
"backends" : [
{
"id" : 0,
"ip" : "192.168.100.254",
"port" : 80,
"status" : "up",
"timeout" : 20,
"weight" : null
},
{
"id" : 0,
"ip" : "192.168.100.254",
"port" : 80,
"status" : "up",
"timeout" : null,
"weight" : null
}
],
"cookiedomain" : "zevenet.cpm",
"cookieinsert" : "true",
"cookiename" : "peasocookie",
"cookiepath" : "/patfh",
"cookiettl" : 20,
"fgenabled" : "false",
"fglog" : "false",
"fgscript" : "check_tcp -H HOST -p PORT",
"fgtimecheck" : 5,
"httpsb" : "false",
"id" : "serv",
"leastresp" : "false",
"persistence" : "COOKIE",
"redirect" : "",
"redirecttype" : "",
"sessionid" : "JSESSIONID",
"ttl" : 18,
"urlp" : "(?i)^/music$",
"vhost" : ""
}
}
Response parameters
The response will be a JSON object with the format below.
Services object for HTTP farms:
| Field | Type | Description |
|---|---|---|
| backends | Object[] | Backends defined in the service. |
| cookiedomain | String | Cookie insertion will be executed if domain matches in the cookie content. Enable cookieinsert field is required. |
| cookieinsert | String | It enables the cookie insertion for backends sticky sessions. The options are true, the profile will search the given cookie in field cookiename, if it doesn’t exist then this cookie will be added, false, not action is taken. |
| cookiename | String | The cookie name (session ID) will be used for identifying the sticky process to backends. Enable cookieinsert field is required. |
| cookiepath | String | It manages the cookie path value for the given cookie. Enable cookieinsert field is required. |
| cookiettl | Number | It is the max time of life for a cookie, in seconds. Enable cookieinsert field is required. |
| fgenabled | String | Enable the use of farm guardian. true farm guardian is enabled and checking backends status, false farm guardian is disabled and not checking backends status. In HTTP profiles a check_tcp is executed by default even if farm guardian is disabled. |
| fglog | String | Enable the use of logs in farm guardian. true enabled, false, disabled. fgenabled is required. |
| fgscript | String | The command that farm guardian will use for checking backends health. true enabled, false, disabled. fgenabled is required. |
| fgtimecheck | Number | farm guardian will check each 'timetocheck’ seconds the backend health status. fgenabled is required. |
| httpsb | String | This parameter indicates to the farm that the backends servers defined in the current service are using the HTTPS language and then the data will be encrypted before to be sent. true, the profile sends the traffic in HTTPS protocol to the backends, false, the profile sends the traffic in HTTP protocol to the backends. |
| id | String | Service’s name, it can’t be modified once the service is created. |
| leastresp | String | It enables the least responde balancing method. true frecuently the profile checks which backend is taking less time to respond in order to send more connections to this one, false profile doesn’t check which backend is taking less time to respond. |
| persistence | String | This parameter defines how the HTTP service is going to manage the client session. The options are: “” empty string, no action is taken, IP the persistence session is done in base of client IP, BASIC the persistence session is done in base of BASIC headers, URL the persistence session is done in base of a field in the URI, PARM the persistence session is done in base of a value at the end of the URI, COOKIE the persistence session is done in base of a cookie name, this cookie has to be created by the backends, and HEADER, the persistence session is done in base of a Header name. |
| redirect | String | It behaves as a special backend, as the client request is answered by a redirect to a new URL automatically. If redirect is configured then the request will not be forwarded to the backend, a Redirect will be responded to the client instead. |
| redirecttype | String | How the redirection will be done, two options: default, the url is taken as an absolute host and path to redirect to, append, the original request path or URI will be appended to the host and path you specified with default option. If redirect field is not configurated, this field will be an empty string. |
| sessionid | String | It is avaliable if persistence field is URL, COOKIE or HEADER, the parameter value will be searched by the farm in the http header and will manage the client session. |
| ttl | Number | Only with persistence. This value indicates the max time of life for an inactive client session (max session age) in seconds. |
| urlp | String | Allows to determine a web service regarding the URL the client is requesting through a specific URL pattern which will be syntactically checked. PCRE regular expression is supported. |
| vhost | String | It specifies the condition determined by the domain name through the same virtual IP and port defined by a HTTP farm. PCRE regular expression is supported. |
Backend object for HTTP farms:
| Field | Type | Description |
|---|---|---|
| id | Number | Backend identifier inside the given service. |
| ip | String | Backend’s IP where the real service is running. |
| port | Number | Backend’s port where the real service is running. |
| status | String | Backend status. The possible values are: up, the farm is running and the backend is ready to receive connections; down, the farm is running and the service has detected that the backend is not working; maintenance, backend is marked as not ready for receiving connections by the administrator, this option is useful for backend’s maintance tasks; undefined, the backend status has been not checked. |
| timeout | Number | It’s the backend timeout to respond a certain request, in seconds. If null system will use global parameter Backends timeout. |
| weight | Number | It’s the weight value for the current real server, backend with higher weight value will receive more connections. Default value null, not special weight used for this backend. |
Create a new Service
Create a new Service
Request example:
curl -k -X POST -H 'Content-Type: application/json' -H "ZAPI_KEY: <ZAPI_KEY_STRING>"
-d '{"id":"newserv"}' https://<zenlb_server>:444/zapi/v3.1/zapi.cgi/farms/FarmHTTP/services
POST /farms/<farmname>/services
Create a service in a given HTTP profile Farm. The farm needs a restart action to apply this change.
Request parameters
| Field | Type | Description | Required |
|---|---|---|---|
| id | String | Service name which is used as unique identifier. Only alphanumeric values are allowed. | true |
Response example:
{
"description" : "New service newserv",
"params" : {
"id" : "newserv"
},
"status" : "needed restart"
}
Modify a Service
Modify a Service
Request example:
curl -k -X PUT -H 'Content-Type: application/json' -H "ZAPI_KEY: <ZAPI_KEY_STRING>"
-d '{"vhost":"www.mywebserver.com","urlp":"^/myapp1$","persistence":"URL",
"redirect":"http://zenloadbalancer.com","ttl":125,"sessionid":"sid","leastresp":"true",
"httpsb":"true"}' https://<zenlb_server>:444/zapi/v3.1/zapi.cgi/farms/FarmHTTP/services/sev2
PUT /farms/<farmname>/services/<id>
Modify the parameters of a service in a HTTP profile. id is the service unique identifier which will be modified.
Request parameters
| Field | Type | Description |
|---|---|---|
| vhost | String | Specifies the condition determined by the domain name through the same virtual IP and port defined by a HTTP profile farm. PCRE regular expression is supported. |
| urlp | String | Allows to determine a web service regarding the URL the client is requesting through a specific URL pattern which will be syntactically checked. PCRE regular expression is supported. |
| redirect | String | It works as a special backend, the client request is answered by a redirect to a new URL automatically. |
| redirecttype | String | How the redirect will be done, two options: default, the url is taken as an absolute host and path to redirect to, append, the original request path or URI will be appended to the host and path you specified in redirect field. This behaviour will apply only if redirect is not an empty value. |
| cookieinsert | String | It enables the cookie insertion for backends sticky sessions. The options are true, the profile will search the given cookie in field cookiename, if it doesn’t exist then this cookie will be added, false, insertion cookie is disabled. |
| cookiename | String | The cookie name (session ID) will be used for identifying the sticky process to backends. Enable cookieinsert field is required. |
| cookiedomain | String | Cookie insertion will be executed if domain matches in the cookie content. Enable cookieinsert field is required. |
| cookiepath | String | It manages the cookie path value for the given cookie, if the URI in the client request or backend response doesn’t match with cookiepath then cookie insertion persistence method is not applied. Enable cookieinsert field is required. |
| cookiettl | Number | It is the max time of life for a cookie, in seconds. Enable cookieinsert field is required. |
| persistence | String | This parameter defines how the HTTP service is going to manage the client session. The options are: “” empty string, no action is taken, IP the persistence session is done in base of client IP, BASIC the persistence session is done in base of BASIC headers, URL the persistence session is done in base of a field in the URI, PARM the persistence session is done in base of a value separated by “;” at the end of the URI, COOKIE the persistence session is done in base of a cookie name, this cookie has to be created by the backends, and HEADER, the persistence session is done in base of a Header name. |
| ttl | Number | Only with persistence. The max time of life for an inactive client session (max session age) in seconds. |
| sessionid | String | It is avaliable if persistence field is URL, COOKIE or HEADER, the parameter value will be searched by the profile in the http header and will manage the client session. |
| leastresp | String | It enables the least responde balancing method. true, frecuently the profile checks which backend is taking less time to respond in order to send more connections to thisone, false, profile doesn’t check which backend is taking less time to respond. |
| httpsb | String | It indicates to the farm that the backends servers defined in the current service are using the HTTPS language and then the data will be encrypted before to be sent. true, the profile sends the traffic in HTTPS protocol to the backends, false, the profile sends the traffic in HTTP protocol to the backends. |
Response example:
{
"description" : "Modify service newsrv in farm newHTTPfarm",
"info" : "There're changes that need to be applied, stop and start farm to apply them!",
"params" : {
"backends" : [],
"cookiedomain" : "",
"cookieinsert" : "false",
"cookiename" : "",
"cookiepath" : "",
"cookiettl" : 0,
"fgenabled" : "false",
"fglog" : "false",
"fgscript" : "",
"fgtimecheck" : 5,
"httpsb" : "true",
"id" : "newsrv",
"leastresp" : "true",
"persistence" : "",
"redirect" : "http://zenloadbalancer.com",
"redirecttype" : "default",
"sessionid" : "sid",
"ttl" : 125,
"urlp" : "^/myapp1$",
"vhost" : "www.mywebserver.com"
},
"status" : "needed restart"
}
Response Parameters
The response will be a json with requested parameters updated and the status field with needed restart value. Restart action need to be taken in order to apply the changes.
Modify farm guardian
Modify farm guardian
Request example:
curl -k -X PUT -H 'Content-Type: application/json' -H "ZAPI_KEY: <ZAPI_KEY_STRING>"
-d '{"fgtimecheck":5,"fgscript":"check_tcp","fgenabled":"true",
"fglog":"true","service":"service1"}' https://<zevenet_server>:444/zapi/v3.1/zapi.cgi/farms/FarmHTTP/fg
Farmguardian is used for advanced monitoring state of backends and totally personalized for your own scripts for the current service. When a problem is detected by farmguardian automatically disables the real server and will be marked as blacklisted.
PUT /farms/<farmname>/fg
Modify the parameters of farm guardian in the given HTTP profile.
Request parameters
| Field | Type | Description | Required |
|---|---|---|---|
| fgtimecheck | Number | The farm guardian will check the backends health status each 'timetocheck’ seconds. | |
| fgscript | String | The command that farm guardian will run for checking backends health status | |
| fgenabled | String | It enables farm guardian in the indicated service. true farm guardian is going to be used for checking backends status, false farm guardian is going to be disabled | |
| fglog | String | Enable the use of logs in farm guardian. true farm guardian is going to log any action, false farm guardian is not going to log any action, it is recommended to enable fglog only for troubleshooting. | |
| service | String | Service name used as unique identifier. | true |
Response example:
{
"description" : "Modify farm FarmHTTP",
"params" : {
"fgenabled" : "true",
"fglog" : "true",
"fgscript" : "checktcp",
"fgtimecheck" : 5,
"service" : "service1"
}
}
Move services
Move services
Request example:
curl -k -X POST -H 'Content-Type: application/json' -H "ZAPI_KEY: <ZAPI_KEY_STRING>"
-d '{"position":0}' https://<zevenet_server>:444/zapi/v3.1/zapi.cgi/farms/FarmHTTP/services/service1/actions
POST /farms/<farmname>/services/<id>/actions
This actions move the given a service Up or Down in the Service List, this option is useful if it is required to change the priority order, note that services are evaluated in the same order that are shown. this action restart the farm automatically.
id is the service unique identifier which will be modified.
Request Parameters
| Field | Type | Description | Required |
|---|---|---|---|
| position | Number | Position where will be the service . First position has the index 0. | true |
Response example:
{
"description" : "Move service",
"message" : "service1 was moved successful.",
"params" : {
"position" : 0
}
}
Delete a Service
Delete a Service
Request example:
curl -k -X DELETE -H 'Content-Type: application/json' -H "ZAPI_KEY: <ZAPI_KEY_STRING>"
https://<zenlb_server>:444/zapi/v3.1/zapi.cgi/farms/FarmHTTP/services/service1
DELETE /farms/<farmname>/services/<id>
Delete a given service of a http profile. id is the service unique identifier which will be deleted.
Response example:
{
"description" : "Delete service service1 in farm FarmHTTP",
"message" : "The service service1 in farm FarmHTTP has been deleted.",
"success" : "true",
"status": "needed restart"
}
HTTP - Services - Backends
List the backends
List the backends
Request example:
curl -k -X GET -H 'Content-Type: application/json' -H "ZAPI_KEY: <ZAPI_KEY_STRING>"
https://<zenlb_server>:444/zapi/v3.1/zapi.cgi/farms/httpfarm/services/service1/backends
GET /farms/<farmname>/services/<id>/backends
Get the list of backends in a service. id is the service unique identifier.
Response example:
{
"description" : "List service backends",
"params" : [
{
"id" : 0,
"ip" : "192.168.0.10",
"port" : 88,
"status" : "up",
"timeout" : 12,
"weight" : 1
},
{
"id" : 1,
"ip" : "192.168.102.245",
"port" : 80,
"status" : "up",
"timeout" : 22,
"weight" : 2
}
]
}
Response Parameters
This call returns a backend object array with the bellow parameters.
| Field | Type | Description |
|---|---|---|
| id | Number | unique identifier for the backend in the service. This identifier is generated by the system. |
| ip | String | Backend’s IP where the real service is listening. |
| port | Number | Backend’s port where the real service is listening. |
| timeout | Number | It’s the backend timeout to respond a certain request, in seconds. |
| weight | Number | It’s the weight value for the current backend. |
| status | String | Backend status. The possible values are: up, the farm is running and the backend is ready to receive connections; down, the farm is running and the service has detected that the backend is not working; maintenance, backend is marked as not ready for receiving connections by the administrator, this option is useful for backend’s maintance tasks; undefined, the backend status has been not checked. |
Create a new Backend
Create a new Backend
Request example:
curl -k -X POST -H 'Content-Type: application/json' -H "ZAPI_KEY: <ZAPI_KEY_STRING>"
-d '{"ip":"192.168.102.244","port":80, "weight":2,"timeout":2}'
https://<zenlb_server>:444/zapi/v3.1/zapi.cgi/farms/httpfarm/services/newsrv/backends
POST /farms/<farmname>/services/<id>/backends
Create a new Backend in a given HTTP profile. id is the service unique identifier.
Request parameters
| Field | Type | Description | Required |
|---|---|---|---|
| ip | String | Backend’s IP where the real service is listening. | true |
| port | Number | Backend’s port where the real service is listening. | true |
| timeout | Number | It’s the backend timeout to respond a certain request. | |
| weight | Number | It’s the weight value for the current backend. |
Response example:
{
"description" : "New service backend",
"message" : "Added backend to service succesfully",
"params" : {
"id" : 0,
"ip" : "192.168.102.244",
"port" : 80,
"timeout" : 2,
"weight" : 2
},
"status" : "needed restart"
}
Response Parameters
The response will be a json with requested parameters updated and the status field with needed restart value if the farm must be restarted. Restart action need to be taken in order to apply the changes.
Modify a Backend
Modify a Backend
Request example:
curl -k -X PUT -H 'Content-Type: application/json' -H "ZAPI_KEY: <ZAPI_KEY_STRING>"
-d '{"ip":"192.168.0.10","port":88,"timeout":12,"service":"sev2", "weight":1}'
https://<zenlb_server>:444/zapi/v3.1/zapi.cgi/farms/FarmHTTP/service/service1/backends/1
PUT /farms/<farmname>/services/<id>/backends/<id>
Modify the parameters of a backend in a service of a HTTP profile.
First id is the service unique identifier, next id is the backend unique identifier.
Request parameters
| Field | Type | Description |
|---|---|---|
| ip | String | Backend’s IP where the real service is listening. |
| port | Number | Backend’s port where the real service is listening. |
| timeout | Number | It’s the backend timeout to respond a certain request, in seconds. |
| weight | Number | It’s the weight value for the current backend. |
Response example:
{
"description" : "Modify service backend",
"info" : "There're changes that need to be applied, stop and start farm to apply them!",
"message" : "Backend modified",
"params" : {
"ip" : "192.168.0.10",
"port" : 88,
"timeout" : 12,
"weight" : 1
},
"status" : "needed restart"
}
Response Parameters
The response will be a json with requested parameters updated and the status field with needed restart value if the farm must be restarted. Restart action need to be taken in order to apply the changes.
Backend in maintenance
Backend in maintenance
Request example:
curl -k -X PUT -H 'Content-Type: application/json' -H "ZAPI_KEY: <ZAPI_KEY_STRING>"
-d '{"action":"maintenance","mode":"cut"}'
https://<zenlb_server>:444/zapi/v3.1/zapi.cgi/farms/httpfarm/services/newsrv/backends/0/maintenance
PUT /farms/<farmname>/services/<id>/backends/<id>/maintenance
Set a given action in a backend of a HTTP farm, available actions are described below.
First id is the service unique identifier, next id is the backend unique identifier.
Request parameters
| Field | Type | Description | Required |
|---|---|---|---|
| action | String | Set the action desired. The actions are: up the backend is ready to receive client requests, maintenance backend is not ready to receive client requests, this action is useful for stopping the backend server without affect to the clients. | |
| mode | String | Choose a maintenance mode. The available options are: drain, the backend doesn’t accept new connections, but it will continue to handle the current connections; or cut, the current connections will be closed. | If this field is not specified, the default mode will be drain. |
Response example:
{
"description" : "Set service backend status",
"params" : {
"action" : "maintenance",
"mode" : "cut"
}
}
Delete a backend
Delete a backend
Request example:
curl -k -X DELETE -H 'Content-Type: application/json' -H "ZAPI_KEY: <ZAPI_KEY_STRING>"
https://<zenlb_server>:444/zapi/v3.1/zapi.cgi/farms/newfarmHTTP/services/service1/backends/4
DELETE /farms/<farmname>/services/<id>/backends/<id>
Delete a given backend in a service of a HTTP profile.
First id is the service unique identifier, next id is the backend unique identifier.
Response example:
{
"description" : "Delete service backend",
"message" : "Backend removed",
"success" : "true"
}
L4xNAT Farms
The L4xNAT profile farm allows to create a L4 farm with a very high performance and much more concurrent connections than load balancer cores in layer 7 like HTTP farm profiles. That layer 4 performance improvement counteracts the advanced content handling that the layer 7 profiles could manage.
Additionally, L4xNAT farms could bind a range of ports, not only one virtual port as is used with other layer 7 profiles. In order to be able to select a range of virtual ports or a specific virtual port in L4xNAT farms, it’s mandatory to select a protocol type. In other case, the farm will be listening on all ports from the virtual IP ( indicated with a character ‘*’ ). Once a TCP or UDP protocol is selected, it will be available to specify a port, several ports between ‘,’ , ports range between ‘:’ or all ports with ‘*’. A combination of all of them will be valid as well.
Retrieve farm by name
Retrieve farm by name
Request example:
curl -k -X GET -H "ZAPI_KEY: <ZAPI_KEY_STRING>"
https://<zevenet_server>:444/zapi/v3.1/zapi.cgi/farms/l4farm
GET /farms/<farmname>
Show all configuration about a given farm.
Response BODY:
{
"backends" : [
{
"id" : 0,
"ip" : "192.168.55.40",
"port" : "88",
"priority" : 2,
"status" : "undefined",
"weight" : 1
},
{
"id" : 1,
"ip" : "192.168.55.41",
"port" : "88",
"priority" : 3,
"status" : "undefined",
"weight" : 2
}
],
"description" : "List farm l4farm",
"ipds" : {
"blacklists" : [],
"dos" : [],
"rbl" : [
"protection_ssh"
]
},
"params" : {
"algorithm" : "weight",
"fgenabled" : "false",
"fglog" : "false",
"fgscript" : "",
"fgtimecheck" : 5,
"listener" : "l4xnat",
"nattype" : "nat",
"persistence" : "",
"protocol" : "tcp",
"status" : "down",
"ttl" : 120,
"vip" : "192.168.100.241",
"vport" : "88"
}
}
Response parameters
The response will be a JSON object with the format below.
Farm Object:
| Field | Type | Description |
|---|---|---|
| ipds | Object | List of IPDS rules applied to this farm. |
| params | Object | Parameters of farm configuration. |
| backends | Object[] | All real servers created in this farm and its configuration. |
IPDS Object:
| Field | Type | Description |
|---|---|---|
| blacklists | String[] | Black list rules applied to the farm. |
| dos | String[] | DoS rules applied to the farm. |
| rbl | String[] | RBL rules applied to the farm. |
Parameters object for L4xNAT farms:
| Field | Type | Description |
|---|---|---|
| algorithm | String | Type of load balancing algorithm used in the Farm. The options are: leastconn connection always to the least connection server, weight connection linear dispatching by weight, prio connections always to the most prio available. |
| listener | String | A listener defines how the farm is going to play with the requests from the clients. informational field, it can’t be modified. |
| nattype | String | How the load balancer layer 4 core is going to operate. The options are: nat also called sNAT mode, the backend responds to the load balancer in order to send the response to the client, dnat the backend will respond directly to the client, load balancer has to be configured as gateway in the backend server. |
| persistence | String | The same ip address will be connected to the same server. The options are: “” empty value, persistence is disabled, ip persistence is enabled through, origin IP is used like unique ID in session. |
| protocol | String | Protocol to be balanced at layer 4. The options are: all the profile will load balance any L4 protocol, tcp the load balancer only will balance TCP L4 protocol, udp the load balancer only will balance UDP L4 protocol, sip the load balancer only will balance SIP or VoIP L7 protocol, ftp the load balancer only will balance FTP L7 protocol, tftp the load balancer only will balance TFTP L7 protocol. |
| status | String | Farm status. The available status values are: down, the farm is not running; needed restart, the farm is up but it is pending of a restart action; critical, the farm is up and all backends are unreachable or maintenance; problem, the farm is up and there are some backend unreachable, but almost a backend is in up status; maintenance, the farm is up and there are backends in up status, but almost a backend is in maintenance mode; up, the farm is up and all the backends are working success. |
| ttl | Number | This field value indicates the number of seconds that the persistence between the client source and the backend is being assigned, in seconds. Persistence must be configured. |
| vip | String | IP of the farm, where the virtual service is listening. |
| vport | String | Port of the farm, where the virtual service is listening. An unique port can be especified, a range port can be especified with separator : and several ports can be especified with separator ,. |
| fgenabled | String | Enables the use of farm guardian. true farm guardian is enabled, false farm guardian is disabled. |
| fglog | String | Enables the use of logs in farm guardian. fgenabled must be enabled. |
| fgscript | String | The command that farm guardian will check. Those available commands are in libexec path. fgenabled must be enabled. |
| fgtimecheck | Number | The farm guardian will check each ‘timetocheck’ seconds. fgenabled must be enabled. |
Backend object for L4xNAT farms:
| Field | Type | Description |
|---|---|---|
| id | Number | ID to identificate the backend in the farm. |
| ip | String | Backend’s IP where the real service is listening. |
| port | Number | Backend’s port where the real service is listening. Empty value is accepted and it will use the same configuration than virtual port(s). |
| status | String | Backend status. The possible values are: up, the farm is running and the backend is ready to receive connections; down, the farm is running and the service has detected that the backend is not working; maintenance, backend is marked as not ready for receiving connections by the administrator, this option is useful for backend’s maintance tasks; undefined, the backend status has been not checked. |
| priority | Number | It’s the priority value for the current real server. Connections always to the most prio available where 1 is the most priority. |
| weight | Number | It’s the weight value for the current real server. Backends with more weight will receive more connections. |
Create a new Farm
Create a new Farm
Request example:
curl -k -X POST -H 'Content-Type: application/json' -H "ZAPI_KEY: <ZAPI_KEY_STRING>"
-d '{"profile":"l4xnat", "vip":"192.168.100.241", "vport":"88","farmname":"newl4farm"}'
https://<zevenet_server>:444/zapi/v3.1/zapi.cgi/farms
POST /farms
Create a new L4xNAT farm.
Request parameters
| Field | Type | Description | Required |
|---|---|---|---|
| farmname | String | Farm name, unique identifier. | true |
| profile | String | The profile of the created Farm. For L4xNAT farms is l4xnat, information message, this value can’t be changed | true |
| vip | String | IP of the farm, where the virtual service is listening. | true |
| vport | String | Port of the farm, where the virtual service is listening. L4xNAT farms allow multiport separated by , or range port separated by :. | true |
Response example:
{
"description" : "Creating farm 'newl4farm'",
"params" : {
"farmname" : "newl4farm",
"interface" : "eth0",
"profile" : "l4xnat",
"vip" : "192.168.100.241",
"vport" : "88"
}
}
Response parameters
The response will be a json with all requested values updated. See response example for more information.
Modify a Farm
Modify a Farm
Request example:
curl -k -X PUT -H 'Content-Type: application/json' -H "ZAPI_KEY: <ZAPI_KEY_STRING>"
-d '{"algorithm":"weight","persistence":"","newfarmname":"l4farm", "protocol":"tcp",
"nattype":"nat","ttl":125,"vip":"178.62.126.152","vport":"81"}'
https://<zenlb_server>:444/zapi/v3.1/zapi.cgi/farms/newfarml4
PUT /farms/<farmname>
Modify the configuration of a L4xNAT farm.
Request parameters
| Field | Type | Description |
|---|---|---|
| newfarmname | String | The new Farm’s name. The farm must be stopped it. |
| algorithm | String | Type of load balancing algorithm used in the Farm. The options are: leastconn connection always to the least connection server, weight connection linear dispatching by weight, prio connections always to the most prio available. |
| listener | String | A listener defines how the farm is going to play with the requests from the clients. informational field, it can’t be modified. |
| nattype | String | How the load balancer layer 4 core is going to operate. The options are: nat also called sNAT mode, the backend responds to the load balancer in order to send the response to the client, dnat the backend will respond directly to the client, load balancer has to be configured as gateway in the backend server. |
| persistence | String | The same ip address will be connected to the same server. The options are: “” empty value, persistence is disabled, ip persistence is enabled through, origin IP is used like unique ID in session. |
| protocol | String | Protocol to be balanced at layer 4. The options are: all the profile will load balance any L4 protocol, tcp the load balancer only will balance TCP L4 protocol, udp the load balancer only will balance UDP L4 protocol, sip the load balancer only will balance SIP or VoIP L7 protocol, ftp the load balancer only will balance FTP L7 protocol, tftp the load balancer only will balance TFTP L7 protocol. |
| ttl | Number | This field value indicates the number of seconds that the persistence between the client source and the backend is being assigned, in seconds. Persistence must be configured. |
| vip | String | IP of the farm, where the virtual service is listening. |
| vport | String | Port of the farm, where the virtual service is listening. An unique port can be especified, a range port can be especified with separator : and several ports can be especified with separator ,. |
Response example:
{
"description" : "Modify farm l4farm",
"params" : {
"algorithm" : "weight",
"nattype" : "nat",
"newfarmname" : "l4farm",
"persistence" : "",
"protocol" : "tcp",
"ttl" : 125,
"vip" : "178.62.126.152",
"vport" : "81"
}
}
Response parameters
The response will be a json with all requested values updated. See response example for more information.
Modify farm guardian
Modify farm guardian
Request example:
curl -k -X PUT -H 'Content-Type: application/json' -H "ZAPI_KEY: <ZAPI_KEY_STRING>"
-d '{"fgtimecheck":5,"fgscript":"Command of Farm Guardian","fgenabled":"true",
"fglog":"true","service":"service1"}' https://<zevenet_server>:444/zapi/v3.1/zapi.cgi/farms/l4farm/fg
Farmguardian is used for advanced monitoring state of backends and totally personalized for your own scripts for the current service. When a problem is detected by farmguardian automatically disables the real server and will be marked as blacklisted.
PUT /farms/<farmname>/fg
Modify the parameters of the farm guardian in a L4xNAT service.
Request parameters
| Field | Type | Description |
|---|---|---|
| fgenabled | String | Enables the use of farm guardian. true farm guardian is enabled, false farm guardian is disabled. |
| fglog | String | Enables the use of logs in farm guardian. fgenabled must be enabled. |
| fgscript | String | The command that farm guardian will check. Those available commands are in libexec path. fgenabled must be enabled. |
| fgtimecheck | Number | The farm guardian will check each 'timetocheck’ seconds. fgenabled must be enabled. |
Response example:
{
"description" : "Modify farm guardian",
"message" : "Success, some parameters have been changed in farm guardian in farm l4farm.",
"params" : {
"fgenabled" : "true",
"fglog" : "true",
"fgscript" : "check_tcp",
"fgtimecheck" : 5
}
}
Response parameters
The response will be a json with all requested values updated. See response example for more information.
Add an IPDS rule
Add an IPDS rule
Request example:
curl -k -X POST -H 'Content-Type: application/json' -H "ZAPI_KEY: <ZAPI_KEY_STRING>"
-d '{"name":"china"}' https://<zevenet_server>:444/zapi/v3.1/zapi.cgi/farms/l4Farm/ipds/blacklists
POST /farms/<farmname>/ipds/<dos|blacklists|rbl>
Apply a blacklists, DoS or RBL rule to a farm.
Request parameters
| Field | Type | Description |
|---|---|---|
| name | String | IPDS rule name used as unique identifier. |
Response example:
{
"description" : "Apply a rule to a farm",
"message" : "Blacklist rule china was applied successful to the farm l4Farm.",
"success" : "true"
}
Remove an IPDS rule
Remove an IPDS rule
Request example:
curl -k -X DELETE -H "ZAPI_KEY: <ZAPI_KEY_STRING>"
https://<zevenet_server>:444/zapi/v3.1/zapi.cgi/farms/l4Farm/ipds/blacklists/china
DELETE /farms/<farmname>/ipds/<dos|blacklists|rbl>/<name>
Remove a blacklist, DoS or RBL rule of IPDS module from a given farm using its idenficator name.
Response example:
{
"description" : "Delete a rule from a farm",
"message" : "Blacklist rule china was removed successful from the farm l4Farm.",
"success" : "true"
}
L4xNAT - Backends
List the backends
List the backends
Request example:
curl -k -X GET -H 'Content-Type: application/json' -H "ZAPI_KEY: <ZAPI_KEY_STRING>"
https://<zenlb_server>:444/zapi/v3.1/zapi.cgi/farms/l4farm/backends
GET /farms/<farmname>/backends
Get the list of backends in a service.
Response example:
{
"description" : "List backends",
"params" : [
{
"id" : 0,
"ip" : "192.5.1.1",
"max_conns" : 400,
"port" : 787,
"priority" : 1,
"status" : "up",
"weight" : 1
},
{
"id" : 1,
"ip" : "192.5.1.3",
"max_conns" : 200,
"port" : 787,
"priority" : 2,
"status" : "up",
"weight" : 1
},
]
}
Response Parameters
This call returns a backend object array with the bellow parameters.
| Field | Type | Description |
|---|---|---|
| id | Number | ID to identificate the backend in the farm. |
| ip | String | Backend’s IP where the real service is listening. |
| port | Number | Backend’s port where the real service is listening. Empty value is accepted and it will use the same configuration than virtual port(s). |
| status | String | Backend status. The possible values are: up, the farm is running and the backend is ready to receive connections; down, the farm is running and the service has detected that the backend is not working; maintenance, backend is marked as not ready for receiving connections by the administrator, this option is useful for backend’s maintance tasks; undefined, the backend status has been not checked. |
| max_conns | Number | It’s the maximum number of concurrent connection for the backend. If this field has the value 0, the backend doesn’t have configurated any connection limit. |
| priority | Number | It’s the priority value for the current real server. Connections always to the most prio available where 1 is the most priority. |
| weight | Number | It’s the weight value for the current real server. Backends with more weight will receive more connections. |
Create a new Backend
Create a new Backend
Request example:
curl -k -X POST -H 'Content-Type: application/json' -H "ZAPI_KEY: <ZAPI_KEY_STRING>"
-d '{"ip":"192.168.5.100","port":8080,"max_conns":400}'
https://<zenlb_server>:444/zapi/v3.1/zapi.cgi/farms/l4farm/backends
POST /farms/<farmname>/backends
Create a new Backend in a given L4xNAT Farm.
Request parameters
| Field | Type | Description | Required |
|---|---|---|---|
| ip | String | Backend’s IP where the real service is listening. | true |
| port | Number | Backend’s port where the real service is listening. Empty value is accepted and it will use the same configuration than virtual port(s). | |
| max_conns | Number | It’s the maximum number of concurrent connection for the backend. If this field has the value 0, the backend doesn’t have configurated any connection limit. | |
| priority | Number | It’s the priority value for the current real server. Connections always to the most prio available where 1 is the most priority. Default value is 1. | |
| weight | Number | It’s the weight value for the current real server. Backends with more weight will receive more connections. Default value is 1. |
Response example:
{
"description" : "New farm backend",
"message" : "Backend added",
"params" : {
"id" : 5,
"ip" : "192.168.5.100",
"port" : 8080,
"max_conns" : 400,
"priority" : null,
"weight" : null
}
}
Response parameters
The response will be a json with all requested values updated. See response example for more information.
Modify a Backend
Modify a Backend
Request example:
curl -k -X PUT -H 'Content-Type: application/json' -H "ZAPI_KEY: <ZAPI_KEY_STRING>"
-d '{"ip":"192.168.5.40","port":8080,"max_conns":220,"priority":4,"weight":7}'
https://<zenlb_server>:444/zapi/v3.1/zapi.cgi/farms/l4farm/backends/2
PUT /farms/<farmname>/backends/<id>
Modify the parameters of a backend in a service of a L4xNAT Farm. id is the backend unique identifier.
Request parameters
| Field | Type | Description |
|---|---|---|
| ip | String | Backend’s IP where the real service is listening. |
| port | Number | Backend’s port where the real service is listening. Empty value is accepted and it will use the same configuration than virtual port(s). |
| max_conns | Number | It’s the maximum number of concurrent connection for the backend. If this field has the value 0, the backend doesn’t have configurated any connection limit. |
| priority | Number | It’s the priority value for the current real server. Connections always to the most prio available where 1 is the most priority. |
| weight | Number | It’s the weight value for the current real server. Backends with more weight will receive more connections. |
Response example:
{
"description" : "Modify backend",
"message" : "Backend modified",
"params" : {
"ip" : "192.168.5.40",
"port" : 8080,
"max_conns" : 220,
"priority" : 4,
"weight" : 7
}
}
Response parameters
The response will be a json with all requested values updated. See response example for more information.
Backend in maintenance
Backend in maintenance
Request example:
curl -k -X PUT -H 'Content-Type: application/json' -H "ZAPI_KEY: <ZAPI_KEY_STRING>"
-d '{"action":"maintenance","mode":"cut"}'
https://<zenlb_server>:444/zapi/v3.1/zapi.cgi/farms/l4farm/backends/1/maintenance
PUT /farms/<farmname>/backends/<id>/maintenance
Set a given action in a backend of a L4xNAT farm. id is the backend unique identifier.
Request parameters
| Field | Type | Description |
|---|---|---|
| action | String | Set the action desired. The actions are: up the backend is ready to receive client requests, maintenance backend is not ready to receive client requests, this action is useful for stopping the backend server without affect to the clients. |
| mode | String | Choose a maintenance mode. The available options are: drain, the backend doesn’t accept new connections, but it will continue to handle the current connections; or cut, the current connections will be closed. |
Response example:
{
"description" : "Set backend status",
"params" : {
"action" : "maintenance",
"mode" : "cut"
}
}
Response parameters
The response will be a json with all requested values updated. See response example for more information.
Delete a backend
Delete a backend
Request example:
curl -k -X DELETE -H 'Content-Type: application/json' -H "ZAPI_KEY: <ZAPI_KEY_STRING>"
https://<zenlb_server>:444/zapi/v3.1/zapi.cgi/farms/l4farm/backends/4
DELETE /farms/<farmname>/backends/<id>
Delete a given backend in a service of a L4xNAT Farm.
id is the backend unique identifier.
Response example:
{
"description" : "Delete backend",
"message" : "Backend removed",
"success" : "true"
}
GSLB Farms
The Global Service Load Balancing, commonly called GSLB, allows to create a load balancing service based on the DNS service hierarchical architecture. This kind of farm provides an authoritative-only DNS with load balancing algorithms and service state detection at DNS application layer.
Retrieve farm by name
Retrieve farm by name
Request example:
curl -k -X GET -H "ZAPI_KEY: <ZAPI_KEY_STRING>"
https://<zevenet_server>:444/zapi/v3.1/zapi.cgi/farms/gslbfarm
GET /farms/<farmname>
Show all configuration about a given farm.
Response example:
{
"description" : "List farm gslbfarm",
"ipds" : {
"blacklists" : [],
"dos" : [],
"rbl" : [
"protection_ssh"
]
},
"params" : {
"status" : "needed restart",
"vip" : "192.168.100.155",
"vport" : 60
},
"services" : [
{
"algorithm" : "roundrobin",
"backends" : [
{
"id" : 1,
"ip" : "127.0.0.1",
"port" : 53,
"status" : "up"
},
{
"id" : 2,
"ip" : "192.168.55.40",
"port" : 53,
"status" : "up"
},
{
"id" : 4,
"ip" : "192.135.10.2",
"port" : 53,
"status" : "up"
}
],
"deftcpport" : 53,
"fgenabled" : "true",
"fgscript" : "check_tcp",
"fgtimecheck" : 5,
"id" : "service1"
},
{
"algorithm" : "prio",
"backends" : [
{
"id" : 1,
"ip" : "127.0.0.1",
"port" : 80,
"status" : "up"
},
{
"id" : 2,
"ip" : "127.0.0.1",
"port" : 80,
"status" : "up"
}
],
"deftcpport" : 80,
"fgenabled" : "false",
"fgscript" : "",
"fgtimecheck" : 5,
"id" : "prioServ"
}
],
"zones" : [
{
"defnamesv" : "ns3",
"id" : "global.com",
"resources" : [
{
"id" : 0,
"rdata" : "ns3",
"rname" : "@",
"ttl" : null,
"type" : "NS"
},
{
"id" : 1,
"rdata" : "192.168.100.155",
"rname" : "ns3",
"ttl" : null,
"type" : "A"
},
{
"id" : 3,
"rdata" : "resource2",
"rname" : "ns2",
"ttl" : null,
"type" : "NS"
},
{
"id" : 4,
"rdata" : "192.168.200.30",
"rname" : "resource2",
"ttl" : null,
"type" : "A"
}
]
},
{
"defnamesv" : "ns1",
"id" : "DOM.com",
"resources" : [
{
"id" : 0,
"rdata" : "ns1",
"rname" : "@",
"ttl" : null,
"type" : "NS"
},
{
"id" : 1,
"rdata" : "192.168.100.155",
"rname" : "ns1",
"ttl" : null,
"type" : "A"
}
]
}
]
}
Response parameters
The response will be a JSON object with the format below.
Farm Object:
| Field | Type | Description |
|---|---|---|
| ipds | Object | List of IPDS rules applied to this farm. |
| params | Object | Parameters of farm configuration. |
| services | Object[] | Array with all services created in this farm and its configuration. |
| zones | Object[] | Array with all zones created in this farm and its configuration. |
IPDS Object:
| Field | Type | Description |
|---|---|---|
| blacklists | String[] | Black lists applied to the farm. |
| dos | String[] | DoS rules applied to the farm. |
| rbl | String[] | RBL rules applied to the farm. |
Parameter object for GSLB farms:
| Field | Type | Description |
|---|---|---|
| vip | String | IP of the farm, where the virtual service is listening. |
| vport | Number | Port of the farm, where the virtual service is listening. |
| status | String | Farm status. The available status values are: down, the farm is not running; needed restart, the farm is up but it is pending of a restart action; critical, the farm is up and all backends are unreachable; problem, the farm is up and there are some backend unreachable, but almost a backend is in up status; up, the farm is up and all the backends are working success. |
Service object for GSLB farms:
| Field | Type | Description |
|---|---|---|
| backends | Object[] | Backends defined in the service. |
| fgenabled | String | Enable the use of farm guardian. true farm guardian is enabled and checking backends status, false farm guardian is disabled and not checking backends status. In GSLB profiles a tcp check is executed by default even if farm guardian is disabled. |
| fgscript | String | The command that farm guardian will use for checking backends health. true enabled, false, disabled. fgenabled is required. |
| fgtimecheck | Number | Farm guardian will check each ‘timetocheck’ seconds the backend health status. fgenabled is required. |
| id | String | Service name which is used as unique identifier. |
| algorithm | String | Type of load balancing algorithm used in the service. The options are: roundrobin, which will balance connections amoung all up backends, or prio which will send all connections to first available backend. |
| deftcpport | Number | Default TCP port health check. This is the health check TCP port that the service is going to check in order to determine that the backend service is alive. An empty value is disabled. |
Backend object for GSLB farms:
| Field | Type | Description |
|---|---|---|
| id | Number | Unique identifier for the backend in the service. This identifier is generated by the system. |
| ip | String | Backend’s IP where the real service is listening. |
| port | Number | Backend’s port where the real service is listening. |
| status | String | Backend status. The possible values are: up, the farm is running and the backend is ready to receive connections; down, the farm is running and the service has detected that the backend is not working; undefined, the backend status has been not checked. |
Zone object:
| Field | Type | Description |
|---|---|---|
| id | Number | Zone’s name used like unique indetificator. |
| defnamesv | String | This will be the entry point root name server that will be available as the Start of Authority (SOA) DNS record. |
| resources | Object[] | Resources defined in the zone. |
Resource object:
| Field | Type | Description |
|---|---|---|
| id | Number | Unique identifier for the resource in the zone. |
| rname | String | The resource name is the nick that DNS service will translate for the real required data in the field rdata. |
| ttl | Number | The Time to Live (optional) value for the current record which it’s needed to determine the length of time that the current name will be cached. |
| type | String | DNS record type. The options are: NS, A, AAAA, CNAME, DYNA, MX, SRV, TXT, PTR or NAPTR). For more information, look at in GSLB - Zones - Resources section. |
| rdata | String | It’s the real data needed by the record type, input value depends of the kind of Resource Name, rname and the resource type, type. |
Create a new Farm
Create a new Farm
Request example:
curl -k -X POST -H 'Content-Type: application/json' -H "ZAPI_KEY: <ZAPI_KEY_STRING>"
-d '{"farmname":"gslbfarm","profile":"gslb","vip":"192.168.100.241","vport":53}'
https://<zevenet_server>:444/zapi/v3.1/zapi.cgi/farms
POST /farms
Create a new GSLB farm.
Request parameters
| Field | Type | Description | Required |
|---|---|---|---|
| farmname | String | Farm name, unique identifier for farm. | true |
| profile | String | The profile of the created Farm. For GSLB farms is gslb. | true |
| vip | String | IP of the farm, where the virtual service is listening. | true |
| vport | Number | Port of the farm, where the virtual service is listening. | true |
Response example:
{
"description" : "Creating farm 'gslbfarm'",
"params" : {
"farmname" : "gslbfarm",
"interface" : "eth0",
"profile" : "gslb",
"vip" : "192.168.100.241",
"vport" : 53
}
}
Response parameters
The response will be a json with all requested values updated. See response example for more information.
Modify a Farm
Modify a Farm
Request example:
curl -k -X PUT -H 'Content-Type: application/json' -H "ZAPI_KEY: <ZAPI_KEY_STRING>"
-d '{"newfarmname":"gslbnewname","vip":"192.168.100.155","vport":60}'
https://<zenlb_server>:444/zapi/v3.1/zapi.cgi/farms/gslbfarm
PUT /farms/<farmname>
Modify the configuration of a GSLB farm.
Request parameters
| Field | Type | Description |
|---|---|---|
| newfarmname | String | The new Farm’s name. Farm must be stopped to do this change. |
| vport | Number | Port of the farm, where the virtual service is listening. |
| vip | String | IP of the farm, where the virtual service is listening. |
Response example:
{
"description" : "Modify farm gslbnewname",
"params" : {
"newfarmname" : "gslbnewname",
"vip" : "192.168.100.155",
"vport" : 60
}
}
Response parameters
The response will be a json with all requested values updated. See response example for more information.
Add an IPDS rule
Add an IPDS rule
Request example:
curl -k -X POST -H 'Content-Type: application/json' -H "ZAPI_KEY: <ZAPI_KEY_STRING>"
-d '{"name":"china"}' https://<zevenet_server>:444/zapi/v3.1/zapi.cgi/farms/gslbFarm/ipds/blacklists
POST /farms/<farmname>/ipds/<dos|blacklists|rbl>
Apply a blacklist, DoS or RBL rule to the farm.
Request parameters
| Field | Type | Description |
|---|---|---|
| name | String | IPDS rule name used as unique identifier. |
Response example:
{
"description" : "Apply a rule to a farm",
"message" : "Blacklist rule china was applied successful to the farm gslbFarm.",
"success" : "true"
}
Remove an IPDS rule
Remove an IPDS rule
Request example:
curl -k -X DELETE -H "ZAPI_KEY: <ZAPI_KEY_STRING>"
https://<zevenet_server>:444/zapi/v3.1/zapi.cgi/farms/gslbFarm/ipds/blacklists/china
DELETE /farms/<farmname>/ipds/<dos|blacklists|rbl>/<name>
Remove a blacklist, DoS or RBL rule from a given farm using its idenficator name.
Response example:
{
"description" : "Delete a rule form a farm",
"message" : "Blacklist rule china was removed successful from the farm gslbFarm.",
"success" : "true"
}
GSLB - Services
A GSLB service represents a group of real servers and an associated algorithm to be used for them. In order to create a new service, you’ve to set a valid identification name and the desired algorithm to use.
The available services are:
Round Robin: equal sharing. An equal balance of traffic to all active real servers. For every incoming connection the balancer assigns the next round robin real server to deliver the request.
Priority: connections always to the most prio available. Balance all connections to the same highest priority server. If this server is down, the connections switch to the next highest server. With this algorithm you can build an Active-Pasive cluster service with several real servers.
Services object for GSLB farms
| Field | Type | Description |
|---|---|---|
| backends | Object[] | Backends defined in the service. |
| fgenabled | String | Enable the use of farm guardian. true farm guardian is enabled and checking backends status, false farm guardian is disabled and not checking backends status. In GSLB profiles a tcp check is executed by default even if farm guardian is disabled. |
| fgscript | String | The command that farm guardian will use for checking backends health. true enabled, false, disabled. fgenabled is required. |
| fgtimecheck | Number | Farm guardian will check each 'timetocheck’ seconds the backend health status. fgenabled is required. |
| id | String | Service name which is used as unique identifier. |
| algorithm | String | Type of load balancing algorithm used in the service. The options are: roundrobin, which will balance connections amoung all up backends, or prio which will send all connections to first available backend. |
| deftcpport | String | Default TCP port health check. This is the health check TCP port that the service is going to check in order to determine that the backend service is alive. An empty value is disabled. |
Create a new Service
Create a new Service
Request example:
curl -k -X POST -H 'Content-Type: application/json' -H "ZAPI_KEY: <ZAPI_KEY_STRING>"
-d '{"id":"service1","algorithm":"roundrobin"}' https://<zenlb_server>:444/zapi/v3.1/zapi.cgi/farms/gslbfarm/services
POST /farms/<farmname>/services
Create a service in a given GSLB Farm. The farm must be restarted to apply this change.
Request parameters
| Field | Type | Description | Required |
|---|---|---|---|
| id | String | Service name which is used as unique identifier. | true |
| algorithm | String | Type of load balancing algorithm used in the service. The options are: roundrobin, which will balance connections amoung all up backends, or prio which will send all connections to first available backend. | true |
Response example:
{
"description" : "New service service1",
"params" : {
"algorithm" : "roundrobin",
"id" : "service1"
},
"status" : "needed restart"
}
Response parameters
The response will be a json with all requested values updated. See response example for more information.
Modify a Service
Modify a Service
Request example:
curl -k -X PUT -H 'Content-Type: application/json' -H "ZAPI_KEY: <ZAPI_KEY_STRING>"
-d '{"deftcpport":53}' https://<zenlb_server>:444/zapi/v3.1/zapi.cgi/farms/gslbfarm/services/service1
PUT /farms/<farmname>/services/<id>
Modify the parameters of a service in a GSLB Farm. id is the service unique identifier which will be modified.
Request parameters
| Field | Type | Description |
|---|---|---|
| deftcpport | Number | This is the health check TCP port that the service is going to check in order to determine that the backend service is alive. |
Response example:
{
"description" : "Modify service service1 in farm gslbfarm",
"info" : "There're changes that need to be applied, stop and start farm to apply them!",
"params" : {
"deftcpport" : 53
},
"status" : "needed restart"
}
Response parameters
The response will be a json with all requested values updated. See response example for more information.
Modify farm guardian
Modify farm guardian
Request example:
curl -k -X PUT -H 'Content-Type: application/json' -H "ZAPI_KEY: <ZAPI_KEY_STRING>"
-d '{"fgtimecheck":"5","fgscript":"check_tcp","fgenabled":"true",
"service":"service1"}' https://<zevenet_server>:444/zapi/v3.1/zapi.cgi/farms/gslbfarm/fg
Farmguardian is used for advanced monitoring state of backends and totally personalized for your own scripts for the current service. When a problem is detected by farmguardian automatically disables the real server and will be marked as blacklisted.
PUT /farms/<farmname>/fg
Modify the parameters of the farm guardian in a GSLB service.
Request parameters
| Field | Type | Description | Required |
|---|---|---|---|
| fgenabled | String | Enable the use of farm guardian. true farm guardian is enabled and checking backends status, false farm guardian is disabled and not checking backends status. In GSLB profiles a tcp check is executed by default even if fgenabled is disabled. | |
| fgscript | String | The command that farm guardian will use for checking backends health. true enabled, false, disabled. | true if fgenabled is enabled. |
| fgtimecheck | Number | Farm guardian will check each 'timetocheck’ seconds the backend health status. fgenabled is required. | |
| service | String | The service identifier, id, which farm guardian will modify. | true |
Response example:
{
"description" : "Modify farm guardian",
"message" : "Success, some parameters have been changed in farm guardian in farm gslbfarm.",
"params" : {
"fgenabled" : "true",
"fgscript" : "check_tcp",
"fgtimecheck" : 5
},
"status" : "needed restart"
}
Response parameters
The response will be a json with all requested values updated. See response example for more information.
Delete a Service
Delete a Service
Request example:
curl -k -X DELETE -H "ZAPI_KEY: <ZAPI_KEY_STRING>"
https://<zenlb_server>:444/zapi/v3.1/zapi.cgi/farms/gslbfarm/services/service1
DELETE /farms/<farmname>/services/<id>
Delete a given service of a GSLB Farm. id is the service unique identifier which will be deleted.
Response example:
{
"description" : "Delete service service1 in farm gslbfarm",
"message" : "The service service1 in farm gslbfarm has been deleted.",
"success" : "true",
"status": "needed restart"
}
GSLB - Services - Backends
This section will manage the real service list associated to a service.
List the backends
List the backends
Request example:
curl -k -X GET -H 'Content-Type: application/json' -H "ZAPI_KEY: <ZAPI_KEY_STRING>"
https://<zenlb_server>:444/zapi/v3.1/zapi.cgi/farms/gslbfarm/services/service1/backends
GET /farms/<farmname>/services/<id>/backends
Get the list of backends in a service. id is the service unique identifier.
Response example:
{
"description" : "List service backends",
"params" : [
{
"id" : 1,
"ip" : "127.0.0.1",
"port":53,
"status":"up"
},
{
"id" : 2,
"ip" : "192.168.55.40",
"port":53,
"status":"up"
}
]
}
Response Parameters
This call returns a backend object array with the bellow parameters.
| Field | Type | Description |
|---|---|---|
| id | Number | Unique identifier for the backend in the service. This identifier is generated by the system. |
| ip | String | IP of the backend, where the real service is listening. |
| port | Number | Backend’s port where the real service is listening. |
| status | String | Backend status. The possible values are: up, the farm is running and the backend is ready to receive connections; down, the farm is running and the service has detected that the backend is not working; undefined, the backend status has been not checked. |
Create a new Backend
Create a new Backend
Request example:
curl -k -X POST -H 'Content-Type: application/json' -H "ZAPI_KEY: <ZAPI_KEY_STRING>"
-d '{"ip":"192.135.10.2"}'
https://<zenlb_server>:444/zapi/v3.1/zapi.cgi/farms/gslbfarm/services/service1/backends
POST /farms/<farmname>/services/<id>/backends
Create a new Backend in a given service in a GSLB Farm. id is the service unique identifier where the backend will be added.
The priority services have 2 backends as maximun, the active host and the passive host.
Request parameters
| Field | Type | Description | Required |
|---|---|---|---|
| ip | String | IP of the backend, where the real service is listening. | true |
Response example:
{
"description" : "New service backend",
"message" : "Added backend to service succesfully",
"params" : {
"id" : 4,
"ip" : "192.135.10.2"
},
"status" : "needed restart"
}
Response parameters
The response will be a json with all requested values updated. See response example for more information.
Modify a Backend
Modify a Backend
Request example:
curl -k -X PUT -H 'Content-Type: application/json' -H "ZAPI_KEY: <ZAPI_KEY_STRING>"
-d '{"ip":"192.168.2.30"}'
https://<zenlb_server>:444/zapi/v3.1/zapi.cgi/farms/gslbfarm/services/service1/backends/1
PUT /farms/<farmname>/services/<id>/backends/<id>
Modify the parameters of a backend in a service of a GSLB Farm.
Note in the PUT above that the first id is the service unique identifier and next id is the backend unique identifier.
Request parameters
| Field | Type | Description |
|---|---|---|
| ip | String | IP of the backend, where the real service is listening. |
Response example:
{
"description" : "Modify service backend",
"info" : "There're changes that need to be applied, stop and start farm to apply them!",
"message" : "Backend modified",
"params" : {
"ip" : "192.168.2.30"
},
"status" : "needed restart"
}
Response parameters
The response will be a json with all requested values updated. See response example for more information.
Delete a backend
Delete a backend
Request example:
curl -k -X DELETE -H 'Content-Type: application/json' -H "ZAPI_KEY: <ZAPI_KEY_STRING>"
https://<zenlb_server>:444/zapi/v3.1/zapi.cgi/farms/gslbfarm/services/service1/backends/3
DELETE /farms/<farmname>/services/<servicename>/backends/<id>
Delete a given backend in a service of a GSLB Farm
Response example:
{
"description" : "Delete service backend",
"message" : "Backend removed",
"success" : "true"
}
GSLB - Zones
The GSLB zone section will describe the DNS domain name, subdomains, aliases, etc., which will be needed to generate a complete DNS zone with additionally load balancing records using the defined services.
Create zone
Create zone
Request example:
curl -k -X POST -H 'Content-Type: application/json' -H "ZAPI_KEY: <ZAPI_KEY_STRING>"
-d '{"id":"global.conf"}'
https://<zenlb_server>:444/zapi/v3.1/zapi.cgi/farms/gslbfarm/zones
POST /farms/<farmname>/zones
Create a DNS zone.
Request Parameters
This call returns a backend object array with the bellow parameters.
| Field | Type | Description | Required |
|---|---|---|---|
| id | Number | Zone’s name used like unique indetificator. | true |
Response example:
{
"description" : "New zone global.com",
"params" : {
"id" : "global.com"
}
}
Response parameters
The response will be a json with all requested values updated. See response example for more information.
Modify a zone
Modify a zone
Request example:
curl -k -X PUT -H 'Content-Type: application/json' -H "ZAPI_KEY: <ZAPI_KEY_STRING>"
-d '{"defnamesv":"ns3"}'
https://<zenlb_server>:444/zapi/v3.1/zapi.cgi/farms/gslbfarm/zones/global.com
PUT /farms/<farmname>/zones/<id>
Modify the parameters of a zone. id is the zone unique identifier which will be modified.
Request Parameters
This call returns a backend object array with the bellow parameters.
| Field | Type | Description |
|---|---|---|
| defnamesv | String | This will be the entry point root name server that will be available as the Start of Authority (SOA) DNS record. |
Response example:
{
"description" : "Modify zone global.com in farm gslbfarm",
"params" : {
"defnamesv" : "ns3"
}
}
Response parameters
The response will be a json with all requested values updated. See response example for more information.
Delete a Zone
Delete a Zone
Request example:
curl -k -X DELETE -H "ZAPI_KEY: <ZAPI_KEY_STRING>"
https://<zenlb_server>:444/zapi/v3.1/zapi.cgi/farms/gslbfarm/zones/dom.com
DELETE /farms/<farmname>/zones/<id>
Delete a given zone of a GSLB Farm.
Response example:
{
"description" : "Delete zone dom.com in farm gslbfarm.",
"message" : "The zone dom.com in farm gslbfarm has been deleted.",
"success" : "true"
}
GSLB - Zones - Resources
Resources defined as the DNS service resolves requests. The possible DNS resources in Zevenet load balances are:
- NS. Name Server type record, it delegates a DNS zone to use the given authoritative name servers.
- A. Address type record, it returns an IPv4 address of a host.
- CNAME. Canonical name type record, it represents an alias of a given name.
- DYNA. Dynamic address type record, it returns a dynamic address specified by a GSLB service already created within the farm configuration according to the algorithm selected for such service.
- AAAA. Address type record, it returns an IPv6 address of a host.
- MX. Mail exchange type record, maps a domain name to a list of message transfer agents for that domain.
- SRV. Service locator type record, Generalized service location record, used for newer protocols instead of creating protocol-specific records such as MX.
- TXT. Text type record, it is used to store any text-based information that can be grabbed when necessary. We most commonly see TXT records used to hold SPF data and verify domain ownership.
- PTR. Pointer record, pointer to a canonical name. Unlike a CNAME, DNS processing stops and just the name is returned. The most common use is for implementing reverse DNS lookups.
- NAPTR. Naming Authority Pointer, Allows regular-expression-based rewriting of domain names which can then be used as URIs, further domain names to lookups, etc.
List the resources
List the resources
Request example:
curl -k -X GET -H "ZAPI_KEY: <ZAPI_KEY_STRING>"
https://<zenlb_server>:444/zapi/v3.1/zapi.cgi/farms/gslbfarm/zones/global.com/resources
GET /farms/<farmname>/zones/<id>/resources
Get the list of resources in a zone. id is the zone unique identifier.
Response example:
{
"description" : "List zone resources",
"params" : [
{
"id" : 0,
"rdata" : "ns3",
"rname" : "@",
"ttl" : null,
"type" : "NS"
},
{
"id" : 1,
"rdata" : "192.168.100.155",
"rname" : "ns3",
"ttl" : null,
"type" : "A"
},
{
"id" : 2,
"rdata" : "192.168.0.9",
"rname" : "resource2",
"ttl" : 10,
"type" : "A"
},
{
"id" : 3,
"rdata" : "resource2",
"rname" : "ns2",
"ttl" : null,
"type" : "NS"
}
]
}
Response Parameters
This call returns a resource object array with the bellow parameters.
| Field | Type | Description |
|---|---|---|
| id | Number | Unique identifier for the resource in the zone. |
| rname | String | The resource name is the nick that DNS service will translate for the real required data in the field rdata. |
| ttl | Number | The Time to Live (optional) value for the current record which it’s needed to determine the length of time that the current name will be cached. |
| type | String | DNS record type. The options are: NS, A, AAAA, CNAME, DYNA, MX, SRV, TXT, PTR or NAPTR). For more information, look at in GSLB - Zones - Resources section. |
| rdata | String | It’s the real data needed by the record type, input value depends of the kind of Resource Name, rname and the resource type, type. |
Create a new resource
Create a new resource
Request example:
curl -k -X POST -H 'Content-Type: application/json' -H "ZAPI_KEY: <ZAPI_KEY_STRING>"
-d '{"rname":"resource2", "rdata":"192.168.0.9", "ttl":10, "type":"A" }'
https://<zenlb_server>:444/zapi/v3.1/zapi.cgi/farms/gslbfarm/zones/global.com/resources
POST /farms/<farmname>/zones/<id>/resources
Create a new resource in a given zone in a GSLB Farm. id is the zone unique identifier which will be modified where the resource will be added.
Request parameters
| Field | Type | Description | Required |
|---|---|---|---|
| rname | String | The resource name is the nick that DNS service will translate for the real required data in the field rdata. | true |
| ttl | Number | The Time to Live value for the current record. It is the maximun number of router devices that the request can through til die. Its useful is that the packet not input in a net loop. | |
| type | String | DNS record type. The options are: NS, A, AAAA, CNAME, DYNA, MX, SRV, TXT, PTR or NAPTR). For more information, look at in GSLB - Zones - Resources section. | true |
| rdata | String | It’s the real data needed by the record type, input value depends of the kind of Resource Name, rname and the resource type, type. If DYNA is selected in type then the rdata value has to be one of the configured services in this zone. | true |
Response example:
{
"description" : "New zone resource",
"message" : "Resource added",
"params" : {
"rdata" : "192.168.0.9",
"rname" : "resource2",
"ttl" : 10,
"type" : "A",
"zone" : "global.com"
}
}
Response parameters
The response will be a json with all requested values updated. See response example for more information.
Modify a resource
Modify a resource
Request example:
curl -k -X PUT -H 'Content-Type: application/json' -H "ZAPI_KEY: <ZAPI_KEY_STRING>"
-d '{"rname":"resource2", "rdata":"192.168.200.30","ttl":null, "type":"A" }'
https://<zenlb_server>:444/zapi/v3.1/zapi.cgi/farms/gslbfarm/zones/global.com/resources/1
PUT /farms/<farmname>/zones/<id>/resources/<id>
Modify the parameters of a resouce in a zone of a GSLB Farm.
First id is the zone unique identifier, next id is the resource unique identifier.
Request parameters
| Field | Type | Description |
|---|---|---|
| rname | String | The resource name is the nick that DNS service will translate for the real required data in the field rdata. |
| ttl | Number | The Time to Live (optional) value for the current record which it’s needed to determine the length of time that the current name will be cached. |
| type | String | DNS record type. The options are: NS, A, AAAA, CNAME, DYNA, MX, SRV, TXT, PTR or NAPTR). For more information, look at in GSLB - Zones - Resources section. |
| rdata | String | It’s the real data needed by the record type, input value depends of the kind of Resource Name, rname and the resource type, type. If type is loaded with value DYNA then rdata has to be loaded with a available service name |
Response example:
{
"description" : "Modify zone resource",
"message" : "Resource modified",
"params" : {
"rdata" : "192.168.200.30",
"rname" : "resource2",
"ttl" : null,
"type" : "A"
},
"success" : "true"
}
Response parameters
The response will be a json with all requested values updated. See response example for more information.
Delete a resource
Delete a resource
Request example:
curl -k -X DELETE -H "ZAPI_KEY: <ZAPI_KEY_STRING>"
https://<zenlb_server>:444/zapi/v3.1/zapi.cgi/farms/gslbfarm/zones/global.com/resources/3
DELETE /farms/<farmname>/zones/<id>/resources/<id>
Delete a given resouce in a zone of a GSLB Farm
Note that in DELETE URI above the first id is the zone unique identifier and next id is the resource unique identifier.
Response example:
{
"description" : "Delete zone resource",
"message" : "Resource removed",
"success" : "true"
}
Datalink Farms
The datalink farm profile allows to create a routes based farm where the backends are uplink routers or gateways. This kind of farm profile is ready to share several uplink WAN router accesses using the load balancer as an uplink channel multiplexor (1 input and several router line outputs). Therefore, the datalink farms could be used as high available communication links and additionally could be used as bandwidth increase joining the amount of bandwidth between the routers backends links.
Retrieve farm by name
Retrieve farm by name
Request example:
curl -k -X GET -H "ZAPI_KEY: <ZAPI_KEY_STRING>"
https://<zevenet_server>:444/zapi/v3.1/zapi.cgi/farms/dlink
GET /farms/<farmname>
Show all configuration about a farm.
Response example:
{
"backends" : [
{
"id" : 0,
"interface" : "eth0",
"ip" : "192.168.100.10",
"priority" : 2,
"status" : "undefined",
"weight" : 2
},
{
"id" : 1,
"interface" : "eth0",
"ip" : "192.168.100.11",
"priority" : 2,
"status" : "undefined",
"weight" : 1
}
],
"description" : "List farm dlink",
"params" : {
"algorithm" : "weight",
"status" : "down",
"vip" : "192.168.100.199"
}
}
Response parameters
The response will be a JSON object with the format below.
Farm Object:
| Field | Type | Description |
|---|---|---|
| params | Object | Parameters of farm configuration. |
| backends | Object[] | Real servers created in this farm and its configuration. |
Parameters object for datalink farms:
| Field | Type | Description |
|---|---|---|
| algorithm | String | Type of load balancing algorithm used in the Farm. The options are: weight, the balancer distributes among all available backends given more charge backends with higher weight atribute or prio, which sends all connections to the backend with the minor value of priority. |
| status | String | Farm status. The available status values are: down, the farm is not running; needed restart, the farm is up but it is pending of a restart action; critical, the farm is up and all backends are unreachable; problem, the farm is up and there are some backend unreachable, but almost a backend is in up status; up, the farm is up and all the backends are working success. |
| vip | String | IP of the farm, where the virtual service is listening. |
Backend object for datalink farms:
| Field | Type | Description |
|---|---|---|
| id | Number | Unique identifier for the backend in the farm. |
| ip | String | IP of the backend, where the real service is listening. |
| interface | String | It’s the local network interface where the backend is connected to. |
| priority | Number | It’s the priority value for the current real server. It will be used when algorithm field is configuration as prio and lower priority will have preference |
| status | String | Backend status. The possible values are: up, the farm is running and the backend is ready to receive connections; down, the farm is running and the service has detected that the backend is not working; undefined, the backend status has been not checked. |
| weight | Number | It’s the weight value for the current real server. It will be used when algorithm field is configuration as weight. |
Create a new Farm
Create a new Farm
Request example:
curl -k -X POST -H 'Content-Type: application/json' -H "ZAPI_KEY: <ZAPI_KEY_STRING>"
-d '{"farmname":"dlink", "vip":"192.168.100.241", "profile":"datalink" }'
https://<zevenet_server>:444/zapi/v3.1/zapi.cgi/farms
POST /farms
Create a new datalink farm.
Request parameters
| Field | Type | Description | Required |
|---|---|---|---|
| farmname | String | Farm name, unique identifier. | true |
| profile | String | The profile of the created Farm. For datalink farms is datalink | true |
| vip | String | IP of the farm, where the virtual service is listening. | true |
Response example:
{
"description" : "Creating farm 'dlink'",
"params" : {
"farmname" : "dlink",
"interface" : "eth0",
"profile" : "datalink",
"vip" : "192.168.100.241"
}
}
Response parameters
The response will be a json with all requested values updated. See response example for more information.
Modify a Farm
Modify a Farm
Request example:
curl -k -X PUT -H 'Content-Type: application/json' -H "ZAPI_KEY: <ZAPI_KEY_STRING>"
-d '{"newfarmname":"dlink2", "vip":"192.168.100.199","algorithm":"weight"}'
https://<zenlb_server>:444/zapi/v3.1/zapi.cgi/farms/dlink
PUT /farms/<farmname>
Modify the configuration of a datalink farm.
Request parameters
| Field | Type | Description |
|---|---|---|
| newfarmname | String | The new farm name. Farm must be stopped. |
| algorithm | String | Type of load balancing algorithm used in the Farm. The options are: weight, the balancer distributes among all available backends given more charge backends with higher weight atribute or prio, which sends all connections to the backend with the minor value of priority. |
| vip | String | IP of the farm, where the virtual service is listening. |
Response example:
{
"description" : "Modify farm dlink",
"params" : {
"algorithm" : "weight",
"vip" : "192.168.100.199",
"newfarmname" : "dlink2"
}
}
Response parameters
The response will be a json with all requested values updated. See response example for more information.
Datalink - Backends
Backends in datalink farms are the gateways through routing the service. The service will multiplexor among this gateways, and some of them is not available, the service uses the other(s).
List the backends
List the backends
Request example:
curl -k -X GET -H 'Content-Type: application/json' -H "ZAPI_KEY: <ZAPI_KEY_STRING>"
https://<zenlb_server>:444/zapi/v3.1/zapi.cgi/farms/dlink/backends
GET /farms/<farmname>/backends
Get the list of backends in a service.
Response example:
[
{
"id" : 6,
"interface" : "eth0",
"ip" : "192.168.100.10",
"priority" : 2,
"status" : "undefined",
"weight" : 2
},
{
"id" : 7,
"interface" : "eth0",
"ip" : "192.168.100.11",
"priority" : 2,
"status" : "undefined",
"weight" : 1
}
]
Response Parameters
This call returns a backend object array with the bellow parameters.
| Field | Type | Description |
|---|---|---|
| id | Number | Unique identifier for the backend in the farm. This identifier is generated by the system. |
| interface | String | It’s the local network interface where the backend is connected to. |
| ip | String | IP of the backend, where the real service is listening. |
| priority | Number | It’s the priority value for the current backend. It will be used when algorithm field is configuration as prio and lower priority will have preference. |
| status | String | Backend status. The possible values are: up, the farm is running and the backend is ready to receive connections; down, the farm is running and the service has detected that the backend is not working; undefined, the backend status has been not checked. |
| weight | Number | It’s the weight value for the current backend. It will be used when algorithm field is configuration as weight. |
Create a new Backend
Create a new Backend
Request example:
curl -k -X POST -H 'Content-Type: application/json' -H "ZAPI_KEY: <ZAPI_KEY_STRING>"
-d '{"ip":"192.168.100.10","interface":"eth0","priority":2,"weight":2}'
https://<zenlb_server>:444/zapi/v3.1/zapi.cgi/farms/dlink/backends
POST /farms/<farmname>/backends
Create a new Backend in a given datalink Farm.
Request parameters
| Field | Type | Description | Required |
|---|---|---|---|
| ip | String | IP of the backend, where the real service is listening. | true |
| interface | String | It’s the local network interface where the backend is connected to. | true |
| priority | Number | It’s the priority value for the current real server.It will be used when algorithm field is configuration as prio and lower priority will have preference. Default value is 1. | |
| weight | Number | It’s the weight value for the current backend. It will be used when algorithm field is configuration as weight. Default value is 1. |
Response example:
{
"description" : "New farm backend",
"message" : "Backend added",
"params" : {
"id" : 6,
"interface" : "eth0",
"ip" : "192.168.100.10",
"priority" : 2,
"weight" : 2
}
}
Response parameters
The response will be a json with all requested values updated. See response example for more information.
Modify a Backend
Modify a Backend
Request example:
curl -k -X PUT -H 'Content-Type: application/json' -H "ZAPI_KEY: <ZAPI_KEY_STRING>"
-d '{"ip":"192.168.102.50","interface":"eth0", "weight":1,"timeout":1}'
https://<zenlb_server>:444/zapi/v3.1/zapi.cgi/farms/datalink/backends/2
PUT /farms/<farmname>/backends/<id>
Modify the parameters of a backend in a service of a datalink Farm. id is the backend unique identifier.
Request parameters
| Field | Type | Description |
|---|---|---|
| ip | String | IP of the backend, where the real service is listening. |
| interface | String | It’s the local network interface where the backend is connected to. |
| priority | Number | It’s the priority value for the current real server.It will be used when algorithm field is configuration as prio and lower priority will have preference. Default value is 1. |
| weight | Number | It’s the weight value for the current backend. |
Response example:
{
"description" : "Modify backend",
"message" : "Backend modified",
"params" : {
"interface" : "eth0",
"ip" : "192.168.102.50",
"timeout" : 1,
"weight" : 1
}
}
Response parameters
The response will be a json with all requested values updated. See response example for more information.
Delete a backend
Delete a backend
Request example:
curl -k -X DELETE -H 'Content-Type: application/json' -H "ZAPI_KEY: <ZAPI_KEY_STRING>"
https://<zenlb_server>:444/zapi/v3.1/zapi.cgi/farms/dlink/backends/4
DELETE /farms/<farmname>/backends/<id>
Delete a given backend in a service of a datalink Farm. id is the backend unique identifier.
Response example:
{
"description" : "Delete backend",
"message" : "Backend removed",
"success" : "true"
}
Network
Zevenet can work with different types of network interfaces.
In this section you can list, create, configure, delete and set an action in NIC, VLAN, virtual and bonding interfaces.
nic: or network interface card, it is a computer hardware component and tis kind of interface is the base for the following kind of interfaces that can be defined and managed in Zevenet.
vlan: or virtual lan card is kind or network interface that provide network segmentation services. More than one vlan can be created through a nic interface.
bonding: Also called by another vendors as trunk interfaces, this kind of nic can be created with more than one nic interface. Zevenet supports 7 different types of bonding interfaces.
virtual: This kind of interface can be created over any kind of interface describew above. This kind of interface should be used for Farms and it is required that the virtual interface is defined in the same subnet than the parent.
List all interfaces
List all interfaces
Request example:
curl -k -X GET -H "ZAPI_KEY: <ZAPI_KEY_STRING>"
https://<zenlb_server>:444/zapi/v3.1/zapi.cgi/interfaces/nic
GET /interfaces
Get a list of interfaces in the system with their configuration.
Response example:
{
"description" : "List interfaces",
"interfaces" : [
{
"gateway" : "",
"ip" : "",
"mac" : "66:eb:31:0e:07:71",
"name" : "bond2",
"netmask" : "",
"status" : "down",
"type" : "bond"
},
{
"gateway" : "192.168.100.1",
"ip" : "192.168.100.121",
"mac" : "a2:6d:80:29:87:c6",
"name" : "bondiface",
"netmask" : "255.255.255.0",
"status" : "up",
"type" : "bond"
},
{
"gateway" : "192.168.100.5",
"ip" : "192.168.100.241",
"mac" : "c2:56:f6:54:ff:a0",
"name" : "eth0",
"netmask" : "255.255.255.0",
"status" : "up",
"type" : "nic",
"is_slave" : "false"
},
{
"gateway" : "192.168.120.1",
"ip" : "192.168.120.120",
"mac" : "c2:56:f6:54:ff:a0",
"name" : "eth0.1",
"netmask" : "255.255.255.0",
"status" : "down",
"type" : "vlan"
},
{
"gateway" : "",
"ip" : "192.168.100.155",
"mac" : "c2:56:f6:54:ff:a0",
"name" : "eth0:virt",
"netmask" : "255.255.255.0",
"status" : "up",
"type" : "virtual"
},
{
"gateway" : "192.168.100.5",
"ip" : "192.168.100.41",
"mac" : "c2:56:f6:54:ff:a0",
"name" : "eth0:virtiface",
"netmask" : "255.255.255.0",
"status" : "down",
"type" : "virtual"
},
{
"gateway" : "192.168.100.5",
"ip" : "192.168.100.102",
"mac" : "62:30:43:36:29:ac",
"name" : "eth1",
"netmask" : "255.255.255.0",
"status" : "up",
"type" : "nic",
"is_slave" : "false"
},
{
"gateway" : "",
"ip" : "",
"mac" : "66:eb:31:0e:07:71",
"name" : "eth2",
"netmask" : "",
"status" : "up",
"type" : "nic",
"is_slave" : "true"
},
{
"gateway" : "",
"ip" : "",
"mac" : "a2:6d:80:29:87:c6",
"name" : "eth3",
"netmask" : "",
"status" : "up",
"type" : "nic",
"is_slave" : "true"
}
]
}
Response parameters
The response will be a JSON object with an interface object array.
Interface object:
| Field | Type | Description |
|---|---|---|
| ip | String | IP of the interface. IP must be in same network segment than parent interface in virtual interface. |
| netmask | String | Netmask of the interface. This value could not be modified in virtual interfaces, it is inherited from parent inteface. |
| gateway | String | Gateway of the interface. This value could not be modified in virtual interfaces, it is inherited from parent inteface. |
| mac | String | MAC of the interface. This value is inherited from the first NIC slave in bonding interfaces. In virtual and VLAN interfaces it is inherited from parent interface. |
| name | String | Interface’s name. It is used as unique identifier. |
| status | String | The values can be up, the interface can receive packets; down, the interface can not receive packets. |
| type | String | The different kind of interfaces are: nic, vlan, virtual or bond. |
| is_slave | String | Only availabe in NIC interfaces, true, the interface is part of a bonding interface, false the interface is not part of a bonding interface. |
Retrieve default gateway
Retrieve default gateway
Request example:
curl -k -X GET -H "ZAPI_KEY: <ZAPI_KEY_STRING>"
https://<zevenet_server>:444/zapi/v3.1/zapi.cgi/interfaces/gateway
GET /interfaces/gateway
The default gateway is the node which to sending all destination traffic that does not reachable locally from any interface in the load balancer.
Get the parameters of the default gateway interface.
Response example:
{
"description" : "Default gateway",
"params" : {
"address" : "192.168.100.5",
"interface" : "eth0"
}
}
Response parameters
| Field | Type | Description |
|---|---|---|
| address | String | It is the IP of the gateway. |
| interface | String | Interface name for the gateway. |
Modify default gateway
Modify default gateway
Request example:
curl -k -X PUT -H 'Content-Type: application/json' -H "ZAPI_KEY: <ZAPI_KEY_STRING>"
-d '{"interface":"eth0","address":"192.168.100.5"}'
https://<zenlb_server>:444/zapi/v3.1/zapi.cgi/interfaces
PUT /interfaces/gateway
Modify the configuration of the gateway interface.
Response example:
{
"description" : "Modify default gateway",
"message" : "The default gateway has been changed successfully",
"success" : "true"
}
Request parameters
| Field | Type | Description |
|---|---|---|
| address | String | It is the IP of the gateway. |
| interface | String | Interface name for the gateway. |
Delete gateway configuration
DELETE /interfaces/gateway
Delete the configuration of the default gateway configuration.
Warning: if the gateway is disconfigured, Zevenet is not going to be reachable from a external network segment.
Delete gateway configuration
Request example:
curl -k -X DELETE -H "ZAPI_KEY: <ZAPI_KEY_STRING>"
https://<zenlb_server>:444/zapi/v3.1/zapi.cgi/interfaces/gateway
Response message
If the gateway is disconfigure from the same network segment, this message will appear, else the connection will lose.
Response example:
{
"description" : "Remove default gateway",
"message" : "The default gateway has been deleted successfully",
"params" : {
"address" : null,
"interface" : null
}
}
Network - NIC interfaces
NIC interfaces are the physical interfaces connected to your Zevenet load balancer.
The system recognizes new interfaces automatically once they are connected.
Using NIC interfaces as parents, other type of interfaces with different characteristics can be created. Available interfaces are: VLAN,virtual and bonding.
List NIC interfaces
GET /interfaces/nic
Get all the parameters of the NIC interfaces.
List NIC interfaces
Request example:
curl -k -X GET -H "ZAPI_KEY: <ZAPI_KEY_STRING>"
https://<zenlb_server>:444/zapi/v3.1/zapi.cgi/interfaces/nic
Response example:
{
"description" : "List NIC interfaces",
"interfaces" : [
{
"gateway" : "192.168.100.5",
"ip" : "192.168.100.241",
"is_slave" : "false",
"mac" : "c2:56:f6:54:ff:a0",
"name" : "eth0",
"netmask" : "255.255.255.0",
"status" : "up"
},
{
"gateway" : "192.168.100.5",
"ip" : "192.168.100.102",
"is_slave" : "false",
"mac" : "62:30:43:36:29:ac",
"name" : "eth1",
"netmask" : "255.255.255.0",
"status" : "up"
},
{
"gateway" : "",
"ip" : "",
"is_slave" : "false",
"mac" : "a2:6d:80:29:87:c6",
"name" : "eth3",
"netmask" : "",
"status" : "down"
}
]
}
Response parameters
The response will be a JSON object with an array of NIC interface objects.
NIC interface object:
| Field | Type | Description |
|---|---|---|
| ip | String | IP of the interface. |
| netmask | String | Define the network segment where the interface is working. |
| gateway | String | IP used to send packets to a different network segment. |
| mac | String | Link layer unique indentifier. It is unmodifiable. |
| name | String | Interface’s name. It is used as interface unique identifier. |
| status | String | The values can be up, the interface can receive packets; down, the interface can not receive packets. |
| is_slave | String | true the interface is part of a bonding interface, false the interface is not part of a bonding interface. |
Retrieve NIC interface
Retrieve NIC interface
Request example:
curl -k -X GET -H "ZAPI_KEY: <ZAPI_KEY_STRING>"
https://<zenlb_server>:444/zapi/v3.1/zapi.cgi/interfaces/nic/eth1
GET /interfaces/nic/<name>
Get all the parameters of a NIC interface. name is the interface unique identifier.
Response example:
{
"description" : "Show NIC interface",
"interface" : {
"gateway" : "192.168.100.5",
"ip" : "192.168.100.102",
"is_slave" : "false",
"mac" : "62:30:43:36:29:ac",
"name" : "eth1",
"netmask" : "255.255.255.0",
"status" : "up"
}
}
Response parameters
| Field | Type | Description |
|---|---|---|
| ip | String | IP of the interface. |
| netmask | String | Define the network segment where the interface is working. |
| gateway | String | IP used to send packets to a different network segment. |
| mac | String | Link layer unique indentifier. It is unmodifiable. |
| name | String | Interface’s name. It is used as interface unique identifier. |
| status | String | The values can be up, the interface can receive packets; down, the interface can not receive packets. |
| type | String | The different kind of interfaces are: nic, vlan, virtual or bond. Each one are defined in their network submenu. |
| is_slave | String | true the interface is part of a bonding interface, false the interface is not part of a bonding interface. |
Modify NIC interface
Modify NIC interface
Request example:
curl -k -X PUT -H 'Content-Type: application/json' -H "ZAPI_KEY: <ZAPI_KEY_STRING>"
-d '{"ip":"192.168.100.102","netmask":"255.255.255.0","gateway":"192.168.100.5"}'
https://<zenlb_server>:444/zapi/v3.1/zapi.cgi/interfaces/nic/eth1
PUT /interfaces/nic/<name>
Modify the parameters of a NIC interface. name is the interface unique identifier.
Request parameters
| Field | Type | Description |
|---|---|---|
| ip | String | IP of the interface. |
| netmask | String | Define the network segment where the interface is working. |
| gateway | String | IP used to send packets of a different network segment. |
Response example:
{
"description" : "Configure nic interface",
"params" : {
"gateway" : "192.168.100.5",
"ip" : "192.168.100.102",
"netmask" : "255.255.255.0"
}
}
Response parameters
The response will be a json with all requested values updated. See response example for more information.
Delete NIC configuration
Delete NIC configuration
Request example:
curl -k -X DELETE -H "ZAPI_KEY: <ZAPI_KEY_STRING>"
https://<zenlb_server>:444/zapi/v3.1/zapi.cgi/interfaces/nic/eth3
DELETE /interfaces/nic/<name>
Delete the configuration for a NIC interface. After this action, the interface will be useless, and ready to be configured again. name is the interface unique identifier.
Response example:
{
"description" : "Delete nic interface",
"message" : "The configuration for the network interface eth3 has been deleted.",
"success" : "true"
}
Set NIC interface action
Set NIC interface action
Request example:
curl -k -X POST -H 'Content-Type: application/json' -H "ZAPI_KEY: <ZAPI_KEY_STRING>"
-d '{"action":"down"}'
https://<zenlb_server>:444/zapi/v3.1/zapi.cgi/interfaces/nic/eth1/actions
POST /interfaces/nic/<name>/actions
Apply an action to a NIC interface. This call lets enable or disable a network interface.
name is the interface unique identifier.
Request parameters
| Field | Type | Description | Required |
|---|---|---|---|
| action | String | Action to apply to the interface. The available values are: up, enable the interface and prepare it for being used; down, disable the interface to not receive or not send packets. | true |
Response example:
{
"description" : "Action on nic interface",
"params" : {
"action" : "up"
}
}
Response parameters
The response will be a json with all requested values updated. See response example for more information.
Network - Bonding interfaces
The Linux bonding interface or also called by another vendors as Trunk provides a method for aggregating multiple network interfaces into a single logical “bonded” interface. The behavior of the bonded interfaces depends upon the mode, Zevenet Load Balancer supports the following methods:
Round-robin policy: Transmit packets in sequential order from the first available slave through the last. This mode provides load balancing and fault tolerance.
Active-backup policy: Only one slave in the bond is active. A different slave becomes active if, and only if, the active slave fails. The bond’s MAC address is externally visible on only one port (network adapter) to avoid confusing the switch. This mode provides fault tolerance. The primary option affects the behavior of this mode.
XOR policy: Transmit based on source MAC address XOR’d with destination MAC address. This selects the same slave for each destination MAC address. This mode provides load balancing and fault tolerance.
Broadcast policy: Transmits everything on all slave interfaces. This mode provides fault tolerance.
IEEE 802.3ad LACP: Creates aggregation groups that share the same speed and duplex settings. Utilizes all slaves in the active aggregator according to the 802.3ad specification.
Pre-requisites:
Network interface support in the base drivers for retrieving the speed and duplex of each slave.
A switch that supports IEEE 802.3ad Dynamic link aggregation. Most switches will require some type of configuration to enable 802.3ad mode.
Adaptive transmit load balancing: Channel bonding that does not require any special switch support. The outgoing traffic is distributed according to the current load (computed relative to the speed) on each slave. Incoming traffic is received by the current slave. If the receiving slave fails, another slave takes over the MAC address of the failed receiving slave.
Pre-requisite:
Base driver support for retrieving the speed of each slave.
Adaptive load balancing: Includes Adaptive transmit load balancing plus receive load balancing for IPV4 traffic, and does not require any special switch support. The receive load balancing is achieved by ARP negotiation. The bonding driver intercepts the ARP Replies sent by the local system on their way out and overwrites the source hardware address with the unique hardware address of one of the slaves in the bonding such that different peers use different hardware addresses for the server.
List Bonding interfaces
List Bonding interfaces
Request example:
curl -k -X GET -H "ZAPI_KEY: <ZAPI_KEY_STRING>"
https://<zenlb_server>:444/zapi/v3.1/zapi.cgi/interfaces/bonding
GET /interfaces/bonding
Get configuration about all bonding interfaces in the system.
Response example:
{
"description" : "List bonding interfaces",
"interfaces" : [
{
"gateway" : "",
"ip" : "",
"mac" : "66:eb:31:0e:07:71",
"mode" : "broadcast",
"name" : "bond2",
"netmask" : "",
"slaves" : [
{
"name" : "eth2"
}
],
"status" : "down"
},
{
"gateway" : "192.168.100.1",
"ip" : "192.168.100.121",
"mac" : "a2:6d:80:29:87:c6",
"mode" : "balance-rr",
"name" : "bondiface",
"netmask" : "255.255.255.0",
"slaves" : [
{
"name" : "eth3"
},
{
"name" : "eth4"
}
],
"status" : "up"
}
]
}
Response parameters
The response will be a JSON object with a bonding interface object array.
The bonding parameters are:
| Field | Type | Description |
|---|---|---|
| ip | String | IP of the interface. |
| netmask | String | Define the network segment where the interface is working. |
| gateway | String | IP used to send packets of a different network segment. |
| mac | String | Link layer unique indentifier. It is the mac of the first NIC interface slave. |
| name | String | Interface’s name. It is used as interface unique identifier. |
| status | String | The values can be up, the interface can receive packets; down, the interface can not receive packets. |
| slaves | Object[] | NIC interface members of the bonding inteface. |
| mode | String | It is the working mode for bonding interface. The options are: balance-rr, Round-robin policy; active-backup, Active-backup policy; balance-xor, XOR policy; broadcast, Broadcast policy; 802.3ad, IEEE 802.3ad LACP; balance-tlb, Adaptive transmit load balancing; balance-alb, Adaptive load balancing. Those values are defined in section Network - Bonding interfaces. |
Slaves object:
| Field | Type | Description |
|---|---|---|
| name | String | Name is the interface unique identifier of the NIC slave. |
Retrieve Bonding interface
Retrieve Bonding interface
Request example:
curl -k -X GET -H "ZAPI_KEY: <ZAPI_KEY_STRING>"
https://<zenlb_server>:444/zapi/v3.1/zapi.cgi/interfaces/bonding/bondiface
GET /interfaces/bonding/<name>
Get all parameters of the interface. name is the interface unique identifier.
Response example:
{
"description" : "Show bonding interface",
"interface" : {
"gateway" : "192.168.100.1",
"ip" : "192.168.100.121",
"mac" : "a2:6d:80:29:87:c6",
"mode" : "balance-rr",
"name" : "bondiface",
"netmask" : "255.255.255.0",
"slaves" : [
{
"name" : "eth3"
},
{
"name" : "eth2"
}
],
"status" : "up"
}
}
Response parameters
The response will be a JSON object with a bonding interface object.
The bonding parameters are:
| Field | Type | Description |
|---|---|---|
| ip | String | IP of the interface. |
| netmask | String | Define the network segment where the interface is working. |
| gateway | String | IP used to send packets of a different network segment. |
| mac | String | Link layer unique indentifier. It is the mac of the first NIC interface slave. |
| name | String | Interface’s name. It is used as interface unique identifier. |
| status | String | The values can be up, the interface can receive packets; down, the interface can not receive packets. |
| slaves | Object[] | NIC interface members of the bonding inteface. |
| mode | String | It is the working mode for bonding interface. The options are: balance-rr, Round-robin policy; active-backup, Active-backup policy; balance-xor, XOR policy; broadcast, Broadcast policy; 802.3ad, IEEE 802.3ad LACP; balance-tlb, Adaptive transmit load balancing; balance-alb, Adaptive load balancing. Those values are defined in Network > Bonding interfaces. |
Slave object:
| Field | Type | Description |
|---|---|---|
| name | String | Name is the interface unique identifier of the NIC slave. |
Create Bonding interface
Create Bonding interface
Request example:
curl -k -X POST -H 'Content-Type: application/json' -H "ZAPI_KEY: <ZAPI_KEY_STRING>"
-d '{"slaves":["eth3","eth2"],"name":"bondiface","mode":"balance-rr"}'
https://<zenlb_server>:444/zapi/v3.1/zapi.cgi/interfaces/bonding
POST /interfaces/bonding
Create a bonding interface joining NIC interfaces.
The bonding MAC address will be taken from its first NIC interface. Bonding mode can’t be changed once the bonding interface is created, but member interfaces can be added or deleted in the bonding interface as needed. A NIC interface will be locked if it is part of a bonding interface.
Request parameters
| Field | Type | Description | Required |
|---|---|---|---|
| name | String | Interface’s name. It is used as interface unique identifier. | true |
| slaves | String[] | All NIC interfaces that build the bonding. It is required the NIC parameter name. | true |
| mode | String | It is the working mode for bonding interface. The options are: balance-rr, Round-robin policy; active-backup, Active-backup policy; balance-xor, XOR policy; broadcast, Broadcast policy; 802.3ad, IEEE 802.3ad LACP; balance-tlb, Adaptive transmit load balancing; balance-alb, Adaptive load balancing. Those values are defined in Network > Bonding interfaces. | true |
Response example:
{
"description" : "Add a bond interface",
"params" : {
"mac" : "a2:6d:80:29:87:c6",
"mode" : "balance-rr",
"name" : "bondiface",
"slaves" : [
{
"name" : "eth3"
},
{
"name" : "eth2"
}
],
"status" : "down"
}
}
Response parameters
The response will be a JSON object with the bonding configurated parameters.
| Field | Type | Description |
|---|---|---|
| mac | String | Link layer unique indentifier. It is the mac of the first NIC interface slave. |
| name | String | Interface’s name. It is used as interface unique identifier. |
| status | String | The values can be up, the interface can receive packets; down, the interface can not receive packets. |
| slaves | Object[] | NIC interfaces which build the bonding inteface. |
| mode | String | It is the working mode for bonding interface. The options are: balance-rr, Round-robin policy; active-backup, Active-backup policy; balance-xor, XOR policy; broadcast, Broadcast policy; 802.3ad, IEEE 802.3ad LACP; balance-tlb, Adaptive transmit load balancing; balance-alb, Adaptive load balancing. Those values are defined in Network > Bonding interfaces. |
Slave object:
| Field | Type | Description |
|---|---|---|
| name | String | Name is the interface unique identifier of the NIC slave. |
Modify Bonding interface
Modify Bonding interface
Request example:
curl -k -X PUT -H 'Content-Type: application/json' -H "ZAPI_KEY: <ZAPI_KEY_STRING>"
-d '{"ip":"192.168.100.121","netmask":"255.255.255.0","gateway":"192.168.100.1"}'
https://<zenlb_server>:444/zapi/v3.1/zapi.cgi/interfaces/bonding/bondiface
PUT /interfaces/bonding/<name>
Modify the parameters of a bonding interface. name is the interface unique identifier.
Request parameters
| Field | Type | Description |
|---|---|---|
| ip | String | IP of the interface. |
| netmask | String | Define the network segment where the interface is working. |
| gateway | String | IP used to send packets of a different network segment. |
Response example:
{
"description" : "Modify bond address",
"params" : {
"gateway" : "192.168.100.1",
"ip" : "192.168.100.121",
"netmask" : "255.255.255.0"
}
}
Response parameters
The response will be a json with all requested values updated. See response example for more information.
Delete Bonding configuration
Delete Bonding configuration
Request example:
curl -k -X DELETE -H "ZAPI_KEY: <ZAPI_KEY_STRING>"
https://<zenlb_server>:444/zapi/v3.1/zapi.cgi/interfaces/bonding/bondiface
DELETE /interfaces/bonding/<name>
Delete the bonding interface configuration. The configuration parameters are: gateway, ip and netmask.
name is the interface unique identifier.
Response example:
{
"description" : "Delete bonding network configuration",
"message" : "The configuration for the bonding interface bondiface has been deleted.",
"success" : "true"
}
Set Bonding interface action
Set Bonding interface action
Request example:
curl -k -X POST -H 'Content-Type: application/json' -H "ZAPI_KEY: <ZAPI_KEY_STRING>"
-d '{"action":"up"}'
https://<zenlb_server>:444/zapi/v3.1/zapi.cgi/interfaces/bonding/bondiface/actions
POST /interfaces/bonding/<name>/actions
Apply an action to a bonding interface. This call lets delete the bonding interface and enable or disable it.
It is needed to delete the bonding interface using destroy action if you want to unlock the used NIC interfaces in the bonding The bonding driver will then restore the MAC addresses that the member interfaces had before they were added to the bonding interface.
name is the interface unique identifier.
Request parameters
| Field | Type | Description | Required |
|---|---|---|---|
| action | String | Action to apply to the interface. The available values are: up enable the interface and prepare it for being used, down disable the interface to not receive or not send packets, destroy delete the bonding and restore the NIC slaves interfaces. | true |
Response example:
{
"description" : "Action on bond interface",
"params" : {
"action" : "up"
}
}
Response parameters
The response will be a json with all requested values updated. See response example for more information.
Add a Bonding slave interface
Add a Bonding slave interface
Request example:
curl -k -X POST -H 'Content-Type: application/json' -H "ZAPI_KEY: <ZAPI_KEY_STRING>"
-d '{"name":"eth4"}'
https://<zenlb_server>:444/zapi/v3.1/zapi.cgi/interfaces/bonding/bondiface/slaves
POST /interfaces/bonding/<name>/slaves
Add a NIC interface as slave to an existing bonding interface.
name is the interface unique identifier.
Request parameters
| Field | Type | Description | Required |
|---|---|---|---|
| name | String | NIC Interface’s name to add to bonding interface. | true |
Response example:
{
"description" : "Add a slave to a bond interface",
"params" : {
"mac" : "a2:6d:80:29:87:c6",
"mode" : "balance-rr",
"name" : "bondiface",
"slaves" : [
{
"name" : "eth3"
},
{
"name" : "eth2"
},
{
"name" : "eth4"
}
],
"status" : "up"
}
}
Response parameters
The response will be a json with updated configurated values. See response example for more information.
Remove a Bonding slave interface
Remove a Bonding slave interface
Request example:
curl -k -X DELETE -H "ZAPI_KEY: <ZAPI_KEY_STRING>"
https://<zenlb_server>:444/zapi/v3.1/zapi.cgi/interfaces/bonding/bondiface/slaves/eth2
DELETE /interfaces/bonding/<name>/slaves/<name>
Delete a NIC slave interface from a bonding interface. Bonding interface must have almost one NIC slave interface.
First name is the DELETE call is the bonding name unique identifier, next name in the DELETE call is the interface name unique identifier of the NIC.
Response example:
{
"description" : "Remove bonding slave interface",
"message" : "The bonding slave interface eth2 has been removed.",
"success" : "true"
}
Network - VLAN interfaces
VLAN interface lets a NIC or bonding interface work in another network, so the IP, gateway and netmask fields could be different of the parent interface. VLAN interface inherits the MAC address from its parent interface.
The VLAN interfaces field name will appear with a dot “.” character that will be used to establish an identifier tag for the vlan interface.
List VLAN interfaces
List VLAN interfaces
Request example:
curl -k -X GET -H "ZAPI_KEY: <ZAPI_KEY_STRING>"
https://<zenlb_server>:444/zapi/v3.1/zapi.cgi/interfaces/vlan
GET /interfaces/vlan
Get all parameters of VLAN interfaces.
Response example:
{
"description" : "List VLAN interfaces",
"interfaces" : [
{
"gateway" : "192.168.120.1",
"ip" : "192.168.120.120",
"mac" : "c2:56:f6:54:ff:a0",
"name" : "eth0.1",
"netmask" : "255.255.255.0",
"parent" : "eth0",
"status" : "down"
}
]
}
Response parameters
The response will be a JSON object with a VLAN interface object array.
The VLAN parameters are:
| Field | Type | Description |
|---|---|---|
| ip | String | IP of the interface. It can be different to the parent inteface IP. |
| netmask | String | Define the network segment where the interface is working. |
| gateway | String | IP used to send packets of a different network segment. |
| mac | String | MAC of the interface. This value is inherited from the parent interface. |
| name | String | Interface’s name. It is used as unique identifier. This name is a chain formated by a parent interface name, a dot character “.” and a number for the vlan network interface or vlan tag. |
| parent | String | It is the Interface used to create this one. |
| status | String | The values can be up the interface can receive packets, down the interface can not receive packets. |
Retrieve VLAN interface
Retrieve VLAN interface
Request example:
curl -k -X GET -H "ZAPI_KEY: <ZAPI_KEY_STRING>"
https://<zenlb_server>:444/zapi/v3.1/zapi.cgi/interfaces/vlan/eth0.1
GET /interfaces/vlan/<name>
Get all parameters of the VLAN interface. name is the interface unique identifier.
Response example:
{
"description" : "Show VLAN interface",
"interface" : {
"gateway" : "192.168.131.1",
"ip" : "192.168.131.155",
"mac" : "c2:56:f6:54:ff:a0",
"name" : "eth0.1",
"netmask" : "255.255.255.0",
"status" : "up"
}
}
Response parameters
| Field | Type | Description |
|---|---|---|
| ip | String | IP of the interface. |
| netmask | String | Define the network segment where the interface is working. |
| gateway | String | IP used to send packets of a different network segment. |
| mac | String | MAC of the interface. This value is inherited from the parent interface. |
| name | String | Interface’s name. It is used as unique identifier. This name is a chain formated by a parent interface name, a dot character “.” and a number for the vlan network interface. |
| status | String | The values can be up the interface can receive packets, down the interface can not receive packets. |
Create VLAN interface
Create VLAN interface
Request example:
curl -k -X POST -H 'Content-Type: application/json' -H "ZAPI_KEY: <ZAPI_KEY_STRING>"
-d '{"ip":"192.168.120.120","netmask":"255.255.255.0","gateway":"192.168.120.1", "name":"eth0.1"}'
https://<zenlb_server>:444/zapi/v3.1/zapi.cgi/interfaces/vlan
POST /interfaces/vlan
Create a VLAN interface from a NIC or bonding interface. The new VLAN interface will share MAC, although the following network parameters must be different: ip, and the following can change: gateway, netmask.
Request parameters
| Field | Type | Description | Required |
|---|---|---|---|
| ip | String | IP of the interface. It must be different to the parent inteface IP. | true |
| netmask | String | Define the network segment where the interface is working. | true |
| gateway | String | IP used to send packets of a different network segment. | true |
| name | String | Interface’s name. It is used as unique identifier. This name is a chain formated by a parent interface name, a dot character “.” and a number for the vlan network interface. | true |
Response example:
{
"description" : "Add a vlan interface",
"params" : {
"gateway" : "192.168.120.1",
"ip" : "192.168.120.120",
"mac" : null,
"name" : "eth0.1",
"netmask" : "255.255.255.0"
}
}
Response parameters
The response will be a json with all requested values updated. See response example for more information.
Modify VLAN interface
Modify VLAN interface
Request example:
curl -k -X PUT -H 'Content-Type: application/json' -H "ZAPI_KEY: <ZAPI_KEY_STRING>"
-d '{"ip":"192.168.131.155","netmask":"255.255.255.0","gateway":"192.168.131.1"}'
https://<zenlb_server>:444/zapi/v3.1/zapi.cgi/interfaces/vlan/eth0.1
PUT /interfaces/vlan/<name>
Modify the parameters of a VLAN interface. name is the interface unique identifier.
Request parameters
| Field | Type | Description |
|---|---|---|
| ip | String | IP of the interface. It can be different to the parent inteface IP. |
| netmask | String | Define the network segment where the interface is working. |
| gateway | String | IP used to send packets of a different network segment. |
Response example:
{
"description" : "Modify VLAN interface",
"params" : {
"gateway" : "192.168.131.1",
"ip" : "192.168.131.155",
"netmask" : "255.255.255.0"
}
}
Response parameters
The response will be a json with all requested values updated. See response example for more information.
Delete VLAN interface
Delete VLAN interface
Request example:
curl -k -X DELETE -H "ZAPI_KEY: <ZAPI_KEY_STRING>"
https://<zenlb_server>:444/zapi/v3.1/zapi.cgi/interfaces/vlan/eth0.1
DELETE /interfaces/vlan/<name>
Delete a VLAN interface. name is the interface unique identifier.
Response example:
{
"description" : "Delete VLAN interface",
"message" : "The VLAN interface eth0.1 has been deleted.",
"success" : "true"
}
Set VLAN interface action
Set VLAN interface action
Request example:
curl -k -X POST -H 'Content-Type: application/json' -H "ZAPI_KEY: <ZAPI_KEY_STRING>"
-d '{"action":"down"}'
https://<zenlb_server>:444/zapi/v3.1/zapi.cgi/interfaces/vlan/eth0.1/actions
POST /interfaces/vlan/<name>/actions
Apply an action to a VLAN interface. This call lets enable or disable a network interface.
name is the name unique identifier.
Request parameters
| Field | Type | Description | Required |
|---|---|---|---|
| action | String | Action to apply to the interface. The available values are: up, enable the interface and prepare it for being used; down, disable the interface to not receive or not send packets. | true |
Response example:
{
"description" : "Action on vlan interface",
"params" : {
"action" : "down"
}
}
Response parameters
The response will be a json with all requested values updated. See response example for more information.
Network - Virtual interfaces
Network interfaces lets users to have another network interface in the same network segment than parent, so virtual interfaces always inherit the network configuration from its parent. The different parameter will be the ip. Virtual interface can be created from NIC, bonding or VLAN. Creating a new virtual interface will appear a field with a colon “:” character that will be used to establish an identification for the virtual interface.
List Virtual interfaces
List Virtual interfaces
Request example:
curl -k -X GET -H "ZAPI_KEY: <ZAPI_KEY_STRING>"
https://<zenlb_server>:444/zapi/v3.1/zapi.cgi/interfaces/virtual
GET /interfaces/virtual
Get all parameters of virtual interfaces.
Response example:
{
"description" : "List virtual interfaces",
"interfaces" : [
{
"gateway" : "",
"ip" : "192.168.100.155",
"mac" : "c2:56:f6:54:ff:a0",
"name" : "eth0:virt",
"netmask" : "255.255.255.0",
"parent" : "eth0",
"status" : "up"
},
{
"gateway" : "192.168.100.5",
"ip" : "192.168.100.41",
"mac" : "c2:56:f6:54:ff:a0",
"name" : "eth0:virtiface",
"netmask" : "255.255.255.0",
"parent" : "eth0",
"status" : "down"
}
]
}
Response parameters
| Field | Type | Description |
|---|---|---|
| ip | String | IP of the interface. The IP must be in same network segment than parent interface. |
| netmask | String | Define the network segment where the interface is working. It inherits from parent interface. |
| gateway | String | IP used to send packets of a different network segment. It inherits from parent interface. |
| mac | String | MAC of the interface. It inherits from parent interface. |
| name | String | Interface’s name. It is used as unique identifier. This name is a chain formated by a parent interface, a colon character “:” and the name for the virtual network interface, alphanumeric characters are allowed. |
| parent | String | It is the Interface used to create this one. |
| status | String | The values can be up, the interface can receive packets; down, the interface can not receive packets. |
Retrieve virtual interface
Retrieve virtual interface
Request example:
curl -k -X GET -H "ZAPI_KEY: <ZAPI_KEY_STRING>"
https://<zenlb_server>:444/zapi/v3.1/zapi.cgi/interfaces/virtual/eth0:virtiface
GET /interfaces/virtual/<name>
Get all parameters of a virtual interface. name is the interface unique identifier.
Response example:
{
"description" : "Show virtual interface",
"interface" : {
"gateway" : "192.168.100.5",
"ip" : "192.168.100.41",
"mac" : "c2:56:f6:54:ff:a0",
"name" : "eth0:virtiface",
"netmask" : "255.255.255.0",
"status" : "down"
}
}
Response parameters
| Field | Type | Description |
|---|---|---|
| ip | String | IP of the interface. The IP must be in same network segment than parent interface. |
| netmask | String | Define the network segment where the interface is working. It inherits from parent interface. |
| gateway | String | IP used to send packets of a different network segment. It inherits from parent interface. |
| mac | String | MAC of the interface. It inherits from parent interface. |
| name | String | Interface’s name. It is used as unique identifier. This name is a chain formated by a parent interface, a colon character “:” and an alphanumeric string for the virtual network interface. |
| parent | String | It is the Interface used to create this one. |
| status | String | The values can be up, the interface can receive packets; down, the interface can not receive packets. |
Create virtual interface
Create virtual interface
Request example:
curl -k -X POST -H 'Content-Type: application/json' -H "ZAPI_KEY: <ZAPI_KEY_STRING>"
-d '{"ip":"192.168.100.41", "name":"eth0:virtiface"}'
https://<zenlb_server>:444/zapi/v3.1/zapi.cgi/interfaces/virtual
POST /interfaces/virtual
Create a virtual interface.
Request parameters
| Field | Type | Description | Required |
|---|---|---|---|
| ip | String | IP of the interface. The IP must be in same network segment than parent interface. | true |
| name | String | Interface’s name. It is used as unique identifier. This name is a chain formated by a parent interface, a colon character “:” and an alphanumeric string for the virtual network interface. | true |
Response example:
{
"description" : "Add a virtual interface",
"params" : {
"gateway" : "192.168.100.5",
"ip" : "192.168.100.41",
"mac" : "c2:56:f6:54:ff:a0",
"name" : "eth0:virtiface",
"netmask" : "255.255.255.0"
}
}
Response parameters
The response will be a json with the interface configuration. See response example for more information.
| Field | Type | Description |
|---|---|---|
| ip | String | IP of the interface. The IP must be in same network segment than parent interface. |
| netmask | String | Define the network segment where the interface is working. It inherits from parent interface. |
| gateway | String | IP used to send packets to a different network segment. It inherits from parent interface. |
| mac | String | MAC of the interface. It inherits from parent interface. |
| name | String | Interface’s name. It is used as unique identifier. This name is a chain formated by a parent interface, a colon character “:” and a alpahnumeric string for the virtual network interface. |
Modify virtual interface
Modify virtual interface
Request example:
curl -k -X PUT -H 'Content-Type: application/json' -H "ZAPI_KEY: <ZAPI_KEY_STRING>"
-d '{"ip":"192.168.131.155"}'
https://<zenlb_server>:444/zapi/v3.1/zapi.cgi/interfaces/virtual/eth0:virtiface
PUT /interfaces/virtual/<name>
Modify the parameters of a virtual interface. name is the interface unique identifier.
Request parameters
| Field | Type | Description |
|---|---|---|
| ip | String | IP of the interface. The IP must be in same network segment than parent interface. |
Response example:
{
"description" : "Modify virtual interface",
"params" : {
"ip" : "192.168.100.10"
}
}
Response parameters
The response will be a json with all requested values updated. See response example for more information.
Delete virtual interface
Delete virtual interface
Request example:
curl -k -X DELETE -H "ZAPI_KEY: <ZAPI_KEY_STRING>"
https://<zenlb_server>:444/zapi/v3.1/zapi.cgi/interfaces/virtual/eth0:virtiface
DELETE /interfaces/virtual/<name>
Delete a virtual interfaces. name is the interface unique identifier.
Response example:
{
"description" : "Delete virtual interface",
"message" : "The virtual interface eth0:virtiface has been deleted.",
"success" : "true"
}
Set Virtual interface action
Set Virtual interface action
Request example:
curl -k -X POST -H 'Content-Type: application/json' -H "ZAPI_KEY: <ZAPI_KEY_STRING>"
-d '{"action":"down"}'
https://<zenlb_server>:444/zapi/v3.1/zapi.cgi/interfaces/virtual/eth0:virtiface/actions
POST /interfaces/virtual/<name>/actions
Apply an action to a virtual interface. This call lets enable or disable a network interface.
name is the interface unique identifier.
Request parameters
| Field | Type | Description | Required |
|---|---|---|---|
| action | String | Action to apply to the interface. The available values are: up, enable the interface and prepare it for being used; down, disable the interface to not receive or not send packets. | true |
Response example:
{
"description" : "Action on virtual interface",
"params" : {
"action" : "down"
}
}
Response parameters
The response will be a json with all requested values updated. See response example for more information.
Network - Floating interfaces
This kind of interface uses a defined virtual interface and mask the outgoing traffic of a nic, bonding or VLAN interface with a child virtual interface. This interface is used for stateful failover behaviour in l4xnat profiles if a cluster is configured.
List Floating interfaces
List Floating interfaces
Request example:
curl -k -X GET -H "ZAPI_KEY: <ZAPI_KEY_STRING>"
https://<zenlb_server>:444/zapi/v3.1/zapi.cgi/interfaces/floating
GET /interfaces/floating
Show all availables or configurated interfaces where a floating IP has been created.
Response example:
{
"description" : "List floating interfaces",
"params" : [
{
"floating_ip" : null,
"interface" : "bondiface",
"interface_virtual" : null
},
{
"floating_ip" : "192.168.100.41",
"interface" : "eth0",
"interface_virtual" : "eth0:virtiface"
},
{
"floating_ip" : null,
"interface" : "eth0.1",
"interface_virtual" : null
},
{
"floating_ip" : null,
"interface" : "eth1",
"interface_virtual" : null
}
]
}
Response parameters
The response will be a JSON object with a floating interface object array:
Floating object:
| Field | Type | Description |
|---|---|---|
| floating_ip | String | Floating IP used in interface. floating_ip must exist as virtual interface child of the interface. |
| interface | String | Interface masked by the floating IP. |
| interface_virtual | String | It is the virtual interface name of the floating IP used to mask the interface. |
Retrieve Floating interface
Retrieve Floating interface
Request example:
curl -k -X GET -H "ZAPI_KEY: <ZAPI_KEY_STRING>"
https://<zenlb_server>:444/zapi/v3.1/zapi.cgi/interfaces/floating/eth0
GET /interfaces/floating/<name>
Shows if an interface has a configured floating IP. If it has one configurated the it will be shown here.
name is the interface unique identifier which can be of type nic, bonding or vlan.
Response example:
{
"description" : "Show floating interface",
"params" : {
"floating_ip" : "192.168.100.41",
"interface" : "eth0",
"interface_virtual" : "eth0:virtiface"
}
}
Response parameters
| Field | Type | Description |
|---|---|---|
| floating_ip | String | Floating IP used in interface. floating_ip must exist as virtual interface child of the interface. |
| interface | String | Interface masked by the floating IP. |
| interface_virtual | String | It is the virtual interface name of the floating IP used to mask the interface. |
Modify Floating interface
Modify Floating interface
Request example:
curl -k -X PUT -H 'Content-Type: application/json' -H "ZAPI_KEY: <ZAPI_KEY_STRING>"
-d '{"floating_ip":"192.168.100.199"}'
https://<zenlb_server>:444/zapi/v3.1/zapi.cgi/interfaces/floating/eth0
PUT /interfaces/floating/<name>
Configure a floating IP for a NIC, bonding or VLAN interface.
name is the interface unique identifier which can be of type nic, bonding or vlan.
Request parameters
| Field | Type | Description | Required |
|---|---|---|---|
| floating_ip | String | Floating IP used in interface. floating_ip must exist as virtual interface child of the interface. | true |
Response example:
{
"description" : "Modify floating interface",
"message" : "Floating interface modification done",
"success" : "true"
}
Delete Floating configuration
Delete Floating configuration
Request example:
curl -k -X DELETE -H "ZAPI_KEY: <ZAPI_KEY_STRING>"
https://<zenlb_server>:444/zapi/v3.1/zapi.cgi/interfaces/floating/eth0
DELETE /interfaces/floating/<name>
Remove the floating IP configuration in an interface.
name is the interface unique identifier which can be of type nic, bonding or vlan.
Response example:
{
"description" : "Remove floating interface",
"message" : "The floating interface has been removed.",
"success" : "true"
}
Monitoring - Statistics
Show information about system and farms. This information will be useful to monitorize the Zevenet load balancer status.
Show system statistics
Show system statistics
Request example:
curl -k -X GET -H "ZAPI_KEY: <ZAPI_KEY_STRING>"
https://<zevenet_server>:444/zapi/v3.1/zapi.cgi/stats
GET /stats
Get global system statistics.
Response example:
{
"description" : "System stats",
"params" : {
"cpu" : {
"cores" : 2,
"idle" : 94.42,
"iowait" : 0,
"irq" : 0,
"nice" : 0,
"softirq" : 0,
"sys" : 2.54,
"usage" : 5.58,
"user" : 3.05
},
"date" : "Fri Jan 27 11:40:32 2017",
"hostname" : "api3",
"load" : {
"Last_1" : 1.17,
"Last_15" : 0.36,
"Last_5" : 0.6
},
"memory" : {
"Buffers" : 21.68,
"Cached" : 147.95,
"MemFree" : 348.06,
"MemTotal" : 2005.01,
"MemUsed" : 1656.95,
"SwapCached" : 2.67,
"SwapFree" : 614.38,
"SwapTotal" : 672,
"SwapUsed" : 57.62
},
"network" : {
"bond0 in in" : 234.72,
"bond0 out out" : 0,
"bond0.10 in in" : 0,
"bond0.10 out out" : 0,
"bond1 in in" : 234.72,
"bond1 out out" : 0,
"bond3 in in" : 815.69,
"bond3 out out" : 4300.38,
"eth0 in in" : 2702.29,
"eth0 out out" : 50701.95,
"eth0.2 in in" : 0,
"eth0.2 out out" : 0,
"eth1 in in" : 234.72,
"eth1 out out" : 0,
"eth2 in in" : 234.72,
"eth2 out out" : 0,
"eth3 in in" : 0,
"eth3 out out" : 0,
"eth4 in in" : 436.89,
"eth4 out out" : 4300.38,
"eth4.6 in in" : 0,
"eth4.6 out out" : 0,
"eth5 in in" : 301.39,
"eth5 out out" : 0,
"eth5.5 in in" : 0,
"eth5.5 out out" : 0,
"eth6 in in" : 77.42,
"eth6 out out" : 0
}
}
}
Response parameters
| Field | Type | Description |
|---|---|---|
| cpu | Object | CPU statistics. |
| date | String | System date. |
| hostname | String | Host’s name. |
| load | Object | Core load statistics. |
| memory | Object | Used memory statistics. |
| network | Object | Network traffic statistics. |
CPU object:
| Field | Type | Description |
|---|---|---|
| cores | Number | Number of cores in the processor. |
| idle | Number | CPU not use by any program. |
| iowait | Number | CPU used by input or output process. |
| irq | Number | CPU used by hardware interrrupcions. |
| nice | Number | CPU scheduling priority. |
| softirq | Number | CPU used by software interrrupcions. |
| sys | Number | CPU used by the system. |
| usage | Number | Total CPU used. |
| user | Number | CPU used by the user. |
Load object:
| Field | Type | Description |
|---|---|---|
| Last_1 | Number | Load system porcentage the last minute. |
| Last_5 | Number | Load system porcentage five minutes ago. |
| Last_15 | Number | Load system porcentage fifteen minutes ago. |
Memory object.
| Field | Type | Description |
|---|---|---|
| Buffers | Number | It’s the memory used by the buffers. This amount is indicated in Mb. |
| Cached | Number | It’s the total memory cached by the system. This amount is indicated in Mb. |
| MemFree | Number | It’s the total free memory not cached by the system. This amount is indicated in Mb. |
| MemTotal | Number | It’s the total ram memory on the system. This amount is indicated in Mb. |
| MemUsed | Number | It’s the memory used by the system. This amount is indicated in Mb. |
| SwapCached | Number | It’s the total cache memory reserved. |
| SwapFree | Number | It’s the total free memory not cached by the system. This amount is indicated in Mb. |
| SwapTotal | Number | It’s the total swap memory reserved. |
| SwapUsed | Number | It’s the swap used memory by the system, on optimal systems should be 0. |
Network object:
| Field | Type | Description |
|---|---|---|
| <interface> in in | Number | Input traffic for this interface. |
| <interface> out out | Number | Output traffic for this interface. |
Show network statistics
Show network statistics
Request example:
curl -k -X GET -H "ZAPI_KEY: <ZAPI_KEY_STRING>"
https://<zevenet_server>:444/zapi/v3.1/zapi.cgi/stats/system/network
GET /stats/system/network
Get a summary of total input and output traffic through a network interface.
Response example:
{
"description" : "Network interfaces usage",
"params" : {
"date" : "Fri Jan 27 11:58:05 2017",
"hostname" : "api3",
"interfaces" : [
{
"in" : "234.72",
"interface" : "bond1",
"out" : "0.00"
},
{
"in" : "77.42",
"interface" : "eth6",
"out" : "0.00"
},
{
"in" : "2703.88",
"interface" : "eth0",
"out" : "50917.65"
},
{
"in" : "815.69",
"interface" : "bond2",
"out" : "4300.38"
}
]
}
}
Response parameters
The response will be a JSON with a key params whose value is an object with the followeing keys:
| Field | Type | Description |
|---|---|---|
| date | String | System date. |
| hostname | String | Host’s name. |
| interfaces | Object[] | Network traffic statistics. |
Interfaces object
| Field | Type | Description |
|---|---|---|
| in | String | Total input traffic in MB. |
| interface | String | Interface name. |
| out | String | Total output trafficin MB. |
Show interfaces statistics
Show interfaces statistics
Request example:
curl -k -X GET -H "ZAPI_KEY: <ZAPI_KEY_STRING>"
https://<zevenet_server>:444/zapi/v3.1/zapi.cgi/stats/system/network/interfaces
GET /stats/system/network/interfaces
Get a summary of each network interface.
Response example:
{
"description" : "Interfaces info",
"params" : {
"bond" : [
{
"in" : "234.72",
"interface" : "bond1",
"ip" : "",
"mac" : "3a:3a:a7:e3:33:73",
"out" : "0.00",
"slaves" : [
"eth2"
],
"status" : "down",
"virtual" : [],
"vlan" : []
},
{
"in" : "815.70",
"interface" : "bond3",
"ip" : "",
"mac" : "ea:00:7d:88:1d:bd",
"out" : "4300.38",
"slaves" : [
"eth4",
"eth5",
"eth6"
],
"status" : "up",
"virtual" : [],
"vlan" : []
},
{
"in" : "234.72",
"interface" : "bond0",
"ip" : "",
"mac" : "c2:d0:d7:64:df:68",
"out" : "0.00",
"slaves" : [
"eth1"
],
"status" : "down",
"virtual" : [],
"vlan" : [
"bond0.10"
]
}
],
"nic" : [
{
"in" : "77.42",
"interface" : "eth6",
"ip" : "",
"mac" : "ea:00:7d:88:1d:bd",
"out" : "0.00",
"status" : "up",
"virtual" : [],
"vlan" : []
},
{
"in" : "2704.81",
"interface" : "eth0",
"ip" : "192.168.101.46",
"mac" : "9e:2e:3e:a5:2e:6a",
"out" : "51039.13",
"status" : "up",
"virtual" : [
"eth0:1",
"eth0:2",
"eth0.2:6"
],
"vlan" : [
"eth0.2"
]
},
{
"in" : "234.72",
"interface" : "eth1",
"ip" : "192.168.101.58",
"mac" : "c2:d0:d7:64:df:68",
"out" : "0.00",
"status" : "up",
"virtual" : [],
"vlan" : []
},
{
"in" : "234.72",
"interface" : "eth2",
"ip" : "",
"mac" : "3a:3a:a7:e3:33:73",
"out" : "0.00",
"status" : "up",
"virtual" : [],
"vlan" : []
},
{
"in" : "0.00",
"interface" : "eth3",
"ip" : "192.168.101.72",
"mac" : "16:97:ab:43:87:02",
"out" : "0.00",
"status" : "down",
"virtual" : [
"eth3:1",
"eth3:8",
"eth3:6"
],
"vlan" : []
},
{
"in" : "436.89",
"interface" : "eth4",
"ip" : "",
"mac" : "ea:00:7d:88:1d:bd",
"out" : "4300.38",
"status" : "up",
"virtual" : [
"eth4.6:5"
],
"vlan" : [
"eth4.6"
]
},
{
"in" : "301.39",
"interface" : "eth5",
"ip" : "",
"mac" : "ea:00:7d:88:1d:bd",
"out" : "0.00",
"status" : "up",
"virtual" : [],
"vlan" : [
"eth5.5"
]
}
]
}
}
Response parameters
The response will be a JSON with a key params whose value is an object with the keys bond and nic.
| Field | Type | Description |
|---|---|---|
| bond | Object[] | Bond interface statistics. |
| nic | Object[] | NIC interface statistics. |
Bond object:
| Field | Type | Description |
|---|---|---|
| in | String | Total input traffic in MB. |
| interface | String | Interface name used as unique identifier. |
| ip | String | Interface’s IP. |
| mac | String | Interface’s MAC. |
| out | String | Total output traffic in MB. |
| slaves | String [] | List of slaves that build the bond interface. |
| status | String | Interface status. The value can be down, the interface is disabled; up, the interface is enabled. |
| virtual | String [] | Virtual interfaces that inherit from this interface. |
| vlan | String [] | VLAN interfaces that inherit from this interface. |
Nic object:
| Field | Type | Description |
|---|---|---|
| in | String | Total input traffic in MB. |
| interface | String | Interface name used as unique identifier. |
| ip | String | Interface’s IP. |
| mac | String | Interface’s MAC. |
| out | String | Total output traffic in MB. |
| status | String | Interface status. The value can be down, the interface is disabled; up, the interface is enabled. |
| virtual | String [] | Virtual interfaces that inherit from this interface. |
| vlan | String [] | VLAN interfaces that inherit from this interface. |
Show memory statistics
Show memory statistics
Request example:
curl -k -X GET -H "ZAPI_KEY: <ZAPI_KEY_STRING>"
https://<zevenet_server>:444/zapi/v3.1/zapi.cgi/stats/system/memory
GET /stats/system/memory
Get a summary of the system memory.
Response example:
{
"description" : "Memory usage",
"params" : {
"Buffers" : 1.01,
"Cached" : 42.47,
"MemFree" : 880.11,
"MemTotal" : 2005.01,
"MemUsed" : 1124.91,
"SwapCached" : 8.27,
"SwapFree" : 565.15,
"SwapTotal" : 672,
"SwapUsed" : 106.84,
"date" : "Fri Jan 27 12:27:11 2017",
"hostname" : "api3"
}
}
Response parameters
The response will be a JSON with a key params whose value is a memory object.
Memory object.
| Field | Type | Description |
|---|---|---|
| Buffers | Number | It’s the memory used by the buffers. This amount is indicated in Mb. |
| Cached | Number | It’s the total memory cached by the system. This amount is indicated in Mb. |
| MemFree | Number | It’s the total free memory not cached by the system. This amount is indicated in Mb. |
| MemTotal | Number | It’s the total ram memory on the system. This amount is indicated in Mb. |
| MemUsed | Number | It’s the memory used by the system. This amount is indicated in Mb. |
| SwapCached | Number | It’s the total cache memory reserved. |
| SwapFree | Number | It’s the total free memory not cached by the system. This amount is indicated in Mb. |
| SwapTotal | Number | It’s the total swap memory reserved. |
| SwapUsed | Number | It’s the swap used memory by the system, on optimal systems should be 0. |
| date | String | System date. |
| hostname | String | Host’s name. |
Show load statistics
Show load statistics
Request example:
curl -k -X GET -H "ZAPI_KEY: <ZAPI_KEY_STRING>"
https://<zevenet_server>:444/zapi/v3.1/zapi.cgi/stats/system/load
GET /stats/system/load
Get a summary of the CPU system load.
Response example:
{
"description" : "System load",
"params" : {
"Last_1" : 0.66,
"Last_15" : 0.39,
"Last_5" : 0.49,
"date" : "Fri Jan 27 13:15:01 2017",
"hostname" : "api3"
}
}
Response parameters
| Field | Type | Description |
|---|---|---|
| Last_1 | Number | Load system usage the last. |
| Last_5 | Number | Load system usage the last five minutes. |
| Last_15 | Number | Load system usage the last fiveteen minutes. |
| date | String | System date. |
| hostname | String | Host’s name. |
Show CPU statistics
Show CPU statistics
Request example:
curl -k -X GET -H "ZAPI_KEY: <ZAPI_KEY_STRING>"
https://<zevenet_server>:444/zapi/v3.1/zapi.cgi/stats/system/cpu
GET /stats/system/cpu
Response example:
{
"description" : "System CPU usage",
"params" : {
"cores" : 2,
"date" : "Fri Jan 27 13:30:52 2017",
"hostname" : "api3",
"idle" : 94.9,
"iowait" : 0,
"irq" : 0,
"nice" : 0,
"softirq" : 0,
"sys" : 3.06,
"usage" : 5.1,
"user" : 2.04
}
}
Response parameters
| Field | Type | Description |
|---|---|---|
| cores | Number | Number of cores in the processor. |
| idle | Number | CPU not use by any program. |
| iowait | Number | CPU used by input or output process. |
| irq | Number | CPU used by hardware interrrupcions. |
| nice | Number | CPU scheduling priority. |
| softirq | Number | CPU used by software interrrupcions. |
| sys | Number | CPU used by the system. |
| usage | Number | Total CPU used. |
| user | Number | CPU used by the user. |
| date | String | System date. |
| hostname | String | Host’s name. |
Show connections statistics
Show connections statistics
Request example:
curl -k -X GET -H "ZAPI_KEY: <ZAPI_KEY_STRING>"
https://<zevenet_server>:444/zapi/v3.1/zapi.cgi/stats/system/connections
GET /stats/system/connections
Get the total current connections in the system. The counter sums any type of tracked connections: ASSURED, ESTABLISHED, SYN_SENT, TIME_WAIT, LISTEN…
Response example:
{
"description" : "System connections",
"params" : {
"connections" : 324
}
}
Response parameters
| Field | Type | Description |
|---|---|---|
| connections | Number | Total tracked connections actually. |
Show number of farms
Show number of farms
Request example:
curl -k -X GET -H "ZAPI_KEY: <ZAPI_KEY_STRING>"
https://<zevenet_server>:444/zapi/v3.1/zapi.cgi/stats/farms/total
GET /stats/farms/total
Show the total of farms created in the system.
Response example:
{
"description" : "Number of farms.",
"number" : 8
}
Response parameters
| Field | Type | Description |
|---|---|---|
| number | Number | It is the number of farms existing in the system. |
Show farms statistics
Show farms statistics
Request example:
curl -k -X GET -H "ZAPI_KEY: <ZAPI_KEY_STRING>"
https://<zevenet_server>:444/zapi/v3.1/zapi.cgi/stats/farms
GET /stats/farms
Get a summary of connections and configuration for all farms in the system.
Response example:
{
"description" : "List all farms stats",
"farms" : [
{
"established" : 0,
"farmname" : "testHttps",
"pending" : 0,
"profile" : "https",
"status" : "up",
"vip" : "192.168.101.20",
"vport" : "120"
},
{
"established" : 0,
"farmname" : "httpFarm",
"pending" : 0,
"profile" : "http",
"status" : "up",
"vip" : "192.168.10.31",
"vport" : "8080"
},
{
"established" : 0,
"farmname" : "testDL",
"pending" : 0,
"profile" : "datalink",
"status" : "up",
"vip" : "192.168.102.72",
"vport" : "eth1"
},
{
"established" : 0,
"farmname" : "testL4",
"pending" : 0,
"profile" : "l4xnat",
"status" : "up",
"vip" : "192.168.10.31",
"vport" : "30"
},
{
"established" : 0,
"farmname" : "testGSLB",
"pending" : 0,
"profile" : "gslb",
"status" : "up",
"vip" : "192.168.10.31",
"vport" : "53"
}
]
}
Response parameters
| Field | Type | Description |
|---|---|---|
| established | Number | Total number of current established connections. |
| farmname | String | Farm name, unique identifier. |
| pending | Number | Number of pending connections. |
| profile | String | Type of farm. The possible values are: datalink, l4xnat, http, https or gslb. Each profile is defined in its section. |
| status | String | Farm status. The available status values are: down, the farm is not running; needed restart, the farm is up but it is pending of a restart action; critical, the farm is up and all backends are unreachable or maintenance; problem, the farm is up and there are some backend unreachable, but almost a backend is in up status; maintenance, the farm is up and there are backends in up status, but almost a backend is in maintenance mode; up, the farm is up and all the backends are working success. |
| vip | String | IP of the farm, where the virtual service is listening. |
| vport | String | Port of the farm, where the virtual service is listening. |
Show a farm statistics
Show a farm statistics
Request example:
curl -k -X GET -H "ZAPI_KEY: <ZAPI_KEY_STRING>"
https://<zevenet_server>:444/zapi/v3.1/zapi.cgi/stats/farms/farmname
GET /stats/farms/<farmname>
Shows the current farm status, theirs backend status and connections. Each farm will response with different object, depending of the profile.
Response example for HTTP farm:
{
"backends" : [
{
"established" : 0,
"id" : 0,
"ip" : "192.168.0.168",
"pending" : 0,
"port" : 80,
"service" : "srv1",
"status" : "up"
}
],
"description" : "List farm stats",
"sessions" : [
{
"client" : "0",
"id" : "0",
"service" : "srv1",
"session" : "192.168.0.186"
}
]
}
Response parameters in HTTP farms
| Field | Type | Description |
|---|---|---|
| backends | Object[] | Show information about backends. |
| sessions | Object[] | Show information about sessions. |
Backend Object
| Field | Type | Description |
|---|---|---|
| established | Number | Total number of established connections. |
| id | Number | Backend unique identifier. |
| ip | String | IP where the real service is listening. |
| pending | Number | Number of pending connections. |
| port | Number | Port where the real service is listening. |
| service | String | Service name used as unique identifier. |
| status | String | Backend status. The possible values are: up, the farm is running and the backend is ready to receive connections; down, the farm is running and the service has detected that the backend is not working; maintenance, backend is marked as not ready for receiving connections by the administrator, this option is useful for backend’s maintance tasks; undefined, the backend status has been not checked. |
Session Object
| Field | Type | Description |
|---|---|---|
| client | String | Client unique identifier. |
| id | String | Backend unique identifier assigned to the client. |
| service | String | Service unique identifier assigned to the client. |
| session | String | Session unique identifier. This value depend of the persistence type. |
Response example for GSLB farm:
{
"backends" : [
{
"id" : 1,
"ip" : "127.0.0.1",
"port" : 53,
"service" : "service1",
"status" : "down"
},
{
"id" : 2,
"ip" : "192.168.55.40",
"port" : 53,
"service" : "service1",
"status" : "down"
},
{
"id" : 4,
"ip" : "192.135.10.2",
"port" : 53,
"service" : "service1",
"status" : "down"
},
{
"id" : 1,
"ip" : "127.0.0.1",
"port" : 80,
"service" : "prioServ",
"status" : "down"
},
{
"id" : 2,
"ip" : "127.0.0.1",
"port" : 80,
"service" : "prioServ",
"status" : "down"
}
],
"client" : {
"edns_big" : 0,
"edns_tc" : 0,
"recvfail" : 0,
"reqs" : 0,
"sendfail" : 0,
"tc" : 0
},
"description" : "List farm stats",
"extended" : {
"badvers" : 0,
"dropped" : 0,
"edns" : 0,
"edns_clientsub" : 0,
"formerr" : 0,
"noerror" : 0,
"notimp" : 0,
"nxdomain" : 0,
"refused" : 0,
"v6" : 0
},
"server" : {
"recvfail" : 0,
"reqs" : 0,
"sendfail" : 0
}
}
Response parameters in GSLB farms
| Field | Type | Description |
|---|---|---|
| backends | Object[] | Show information about the backends. |
| client | Object | Statistics related to the client. |
| extended | Object | Extended information about the service. |
| server | Object | Statistics related with the server. |
Backend object
| Field | Type | Description |
|---|---|---|
| id | Number | Backend unique identifier. |
| ip | String | IP where the real service is listening. |
| port | Number | Port where the real service is listening. |
| service | String | Service name used as unique identifier. |
| status | String | Backend status. The possible values are: up, the farm is running and the backend is ready to receive connections; down, the farm is running and the service has detected that the backend is not working; undefined, the backend status has been not checked. |
Client object
| Field | Type | Description |
|---|---|---|
| edns_big | Number | Responses that were greater than 512 bytes. |
| edns_tc | Number | The client’s specified extended dns buffer size was too small for the data requested. |
| recvfail | Number | Number of UDP errors, where the OS indicated that something bad happened on receiving. |
| reqs | Number | Total number of UDP request handled by the server. |
| sendfail | Number | Number of UDP errors, where the OS indicated that something bad happened on sending. |
| tc | Number | Responses that were truncated with the TC bit set. |
Extended object
| Field | Type | Description |
|---|---|---|
| badvers | Number | Request that had an EDNS OPT-RR with a version not supported. |
| dropped | Number | Dropped requests for malformed format. |
| edns | Number | Request contained an EDNS OPT-RR. |
| edns_clientsub | Number | Subset of edns requests that specified the edns_client_subnet option. |
| formerr | Number | Request was badly-formatted, but was sane enough that we did send a response with the rcode FORMERR. |
| noerror | Number | Successful requests. |
| notimp | Number | Requested service not implemented by this daemon, such as zone transfer requests. |
| nxdomain | Number | Request for a non-existant domainname. |
| refused | Number | Request was refused by the server because the server is not authoritative for the queried name. |
| v6 | Number | Request from an IPv6 client. |
Server object
| Field | Type | Description |
|---|---|---|
| recvfail | Number | Number of TCP errors, where the OS indicated that something bad happened on receiving. |
| reqs | Number | Total number of TCP request handled by the server. |
| sendfail | Number | Number of TCP errors, where the OS indicated that something bad happened on sending. |
Response example for L4xNAT farm:
{
"backends" : [
{
"established" : 5,
"id" : 1,
"ip" : "192.168.5.40",
"pending" : 0,
"port" : "8080",
"status" : "maintenance"
},
{
"established" : null,
"id" : 3,
"ip" : "192.5.1.1",
"pending" : 0,
"port" : "787",
"status" : "down"
},
{
"established" : null,
"id" : 5,
"ip" : "192.168.5.100",
"pending" : 0,
"port" : "8080",
"status" : "up"
}
],
"description" : "List farm stats"
}
Response parameters in L4xNAT farms
The response will be a JSON with key backends and value an object array with the below parameters.
Backend object:
| Field | Type | Description |
|---|---|---|
| established | Number | Total number of current established connections. |
| id | Number | Backend unique identifier. |
| ip | String | IP where the real service is listening. |
| pending | Number | Number of pending connections. |
| port | Number | Port where the real service is listening. |
| status | String | Backend status. The possible values are: up, the farm is running and the backend is ready to receive connections; down, the farm is running and the service has detected that the backend is not working; maintenance, backend is marked as not ready for receiving connections by the administrator, this option is useful for backend’s maintance tasks; undefined, the backend status has been not checked. |
Response parameters in datalink farms
Datalink farms statistics is not available actually.
Show module status
Show module status
Request example:
curl -k -X GET -H "ZAPI_KEY: <ZAPI_KEY_STRING>"
https://<zevenet_server>:444/zapi/v3.1/zapi.cgi/stats/farms/modules
GET /stats/farms/modules
Get a summary of modules statistics. This call shows each module status, number of configured, the number of farms put down and up.
The definition about modules is in Farms section.
Response example:
{
"description" : "Module status",
"params" : {
"dslb" : {
"critical" : 0,
"down" : 1,
"problem" : 0,
"total" : 2,
"up" : 1
},
"gslb" : {
"critical" : 0,
"down" : 0,
"problem" : 0,
"total" : 1,
"up" : 1
},
"lslb" : {
"critical" : 0,
"down" : 2,
"problem" : 0,
"total" : 4,
"up" : 2
}
}
}
Response parameters
The response will be a JSON with three keys: dslb, gslb and lslb.
| Field | Type | Description |
|---|---|---|
| critical | Number | Number of farms in critical status. The farm is critical when it is up and all backends are unreachable (down or maintenance). |
| down | Number | Number of stopped farms. The farms are stopped by system administrator. |
| problem | Number | Number of farms in problem status. The farm is problem when it is up and almost a backend is in down status. |
| total | Number | Number of total farms. |
| up | Number | Number of running farms. Here is displayed maintenanced and need to restart farm status. |
Show module statistics
Show module statistics
Request example:
curl -k -X GET -H "ZAPI_KEY: <ZAPI_KEY_STRING>"
https://<zevenet_server>:444/zapi/v3.1/zapi.cgi/stats/farms/modules/lslb
GET /stats/farms/modules/<module>
Show farms statistics of a specified module.
The available values for the module parameter are: lslb, gslb or dslb.
Response example:
{
"description" : "List lslb farms stats",
"farms" : [
{
"established" : 0,
"farmname" : "newfarm",
"pending" : 0,
"profile" : "http",
"status" : "up",
"vip" : "192.168.100.199",
"vport" : "40"
},
{
"established" : 0,
"farmname" : "nwl4farm",
"pending" : 0,
"profile" : "l4xnat",
"status" : "down",
"vip" : "192.168.100.241",
"vport" : "88"
},
{
"established" : 0,
"farmname" : "l4farm",
"pending" : 0,
"profile" : "l4xnat",
"status" : "up",
"vip" : "192.168.100.102",
"vport" : "70"
}
]
}
Response parameters
The response will be a JSON object with information about farms in the module.
| Field | Type | Description |
|---|---|---|
| established | Number | Total number of current established connections. |
| farmname | String | Farm name, unique identifier for farms. |
| pending | Number | Number of pending connections. |
| profile | String | Type of farm. The possible values are: datalink, l4xnat, http, https or gslb. Each profile is defined themself section. |
| status | String | Farm status. The available status values are: down, the farm is not running; needed restart, the farm is up but it is pending of a restart action; critical, the farm is up and all backends are unreachable or maintenance; problem, the farm is up and there are some backend unreachable, but almost a backend is in up status; maintenance, the farm is up and there are backends in up status, but almost a backend is in maintenance mode; up, the farm is up and all the backends are working success. |
| vip | String | IP of the farm, where the virtual service is listening. |
| vport | String | Port of the farm, where the virtual service is listening. |
Monitoring - Graphs
This section is useful to monitorize the internal load balancer system to detect problems through the parameters of CPU usage, swap memory, ram memory, all configured nework interfaces, load and hard disk storage.
Also, you’ll be able to access to the weekly, mothly and yearly history.
Graphs with information are responded in base64 format.
List available graphs
List available graphs
Request example:
curl -k -X GET -H "ZAPI_KEY: <ZAPI_KEY_STRING>"
https://<zevenet_server>:444/zapi/v3.1/zapi.cgi/graphs
GET /graphs
Show an object with all available graphs in the system. It shows the possible request that can be made.
Response example:
{
"description" : "These are the possible graphs, you`ll be able to access to the daily, weekly, monthly or yearly graph",
"farms" : [
"l4farm",
"newfarm",
"gslbfarm",
"nwl4farm",
"httpweb"
],
"interfaces" : [
"eth0.1",
"eth2",
"eth1",
"eth3",
"bondiface",
"eth0"
],
"system" : [
"cpu",
"load",
"ram",
"swap",
{
"disk" : [
"root/",
"root/boot",
"root/usr/local/zenloadbalancer/config",
"root/var/log"
]
}
]
}
Response parameters
The response will be a JSON three types of graphs, farms, interfaces and system.
| Field | Type | Description |
|---|---|---|
| farms | String[] | List of farm graphs availables. |
| interfaces | String[] | List of interfaces graphs availables. |
| system | Object[] | List of system graphs availables. The array has an object with an array wich it indicates disk mount points. |
System object:
System object contains an array list related with the system, and a disk object with the next format.
| Field | Type | Description |
|---|---|---|
| disk | String[] | The values of this array are all existing mount points in the system, each one has available graphs. |
Show graphs
Show graphs
Request example for a farm:
curl -k -X GET -H "ZAPI_KEY: <ZAPI_KEY_STRING>"
https://<zevenet_server>:444/zapi/v3.1/zapi.cgi/graphs/farms/httpweb
Request example for an interface:
curl -k -X GET -H "ZAPI_KEY: <ZAPI_KEY_STRING>"
https://<zevenet_server>:444/zapi/v3.1/zapi.cgi/graphs/interfaces/eth3
Request example for a disk:
curl -k -X GET -H "ZAPI_KEY: <ZAPI_KEY_STRING>"
https://<zevenet_server>:444/zapi/v3.1/zapi.cgi/graphs/system/disk/root/boot
GET /graphs/<graph>
The available values for graph are:
| Value | Description |
|---|---|
farms/<farmname> |
farmname, farm unique identifier. |
interfaces/<interface> |
interface, interface unique identifier. |
system/<system> |
system, possible system graphs are: cpu, load, ram or swap. |
system/disk/<mount point> |
mount point, is a value of disk object, returned by ‘GET /graphs’ call. |
Response example:
{
"description" : "Get cpu graphs",
"graphs" : [
{
"frequency" : "daily",
"graph" : "PNG IN BASE 64"
},
{
"frequency" : "weekly",
"graph" : "PNG IN BASE 64"
},
{
"frequency" : "monthly",
"graph" : "PNG IN BASE 64"
},
{
"frequency" : "yearly",
"graph" : "PNG IN BASE 64"
}
]
}
Response parameters
| Field | Type | Description |
|---|---|---|
| frequency | String | Time period used to generate the graph. The possible values are: daily, weekly, monthly or yearly. |
| graphs | String | Graph in base 64 format. |
Show frequency graph
Show frequency graph
Request example for a farm:
curl -k -X GET -H "ZAPI_KEY: <ZAPI_KEY_STRING>"
https://<zevenet_server>:444/zapi/v3.1/zapi.cgi/graphs/farms/httpweb/daily
Request example for an interface:
curl -k -X GET -H "ZAPI_KEY: <ZAPI_KEY_STRING>"
https://<zevenet_server>:444/zapi/v3.1/zapi.cgi/graphs/interfaces/eth3/monthly
Request example for a disk:
curl -k -X GET -H "ZAPI_KEY: <ZAPI_KEY_STRING>"
https://<zevenet_server>:444/zapi/v3.1/zapi.cgi/graphs/system/disk/root/boot/yearly
GET /graphs/<graph>/<frequency>
The available values for graph are:
| Value | Description |
|---|---|
farms/<farmname> |
farmname, farm unique identifier. |
interfaces/<interface> |
interface, interface unique identifier. |
system/<system> |
system, possible system graphs are: cpu, load, ram or swap. |
system/disk/<mount point> |
mount point, is a value of disk object, returned by 'GET /graphs’ call. |
The available values for frequency are:
| Field | Type | Description |
|---|---|---|
| frequency | String | Time period used to generate the graph. The possible values are: daily, weekly, monthly or yearly. |
Response example:
{
"description" : "Get farm graphs",
"graph" : "PNG IN BASE 64"
}
Response parameters
| Field | Type | Description |
|---|---|---|
| graphs | String | Graph in base 64 format. |
IPDS
This module is the implementation of a IPS (Intrusion Prevention System) and IDS (Intrusion Detection System) system for offering to the user a security layer. IPDS module inspects the traffic just before to reach the Load Balancing modules LSLB or GSLB, if the traffic is detected as malicious then it will be rejected.
It works applying security rules to the system which will be defined as object of different nature. Each one offers a solution for external malicious or suspicious action. This tool helps to the system administrators controlling threats and attacks.
The available rules to apply to Zevenet can be blacklists, DoS or RBL.
List all ipds rules
List ipds rules
Request example:
curl -k -X GET -H "ZAPI_KEY: <ZAPI_KEY_STRING>"
https://<zenlb_server>:444/zapi/v3.1/zapi.cgi/ipds
GET /ipds
List all ipds rules that exits in the system.
Response example:
{
"description" : "List the available IPDS rules.",
"params" : [
{
"name" : "dosrst",
"rule" : "dos",
"type" : "farm"
},
{
"name" : "ssh_brute_force",
"rule" : "dos",
"type" : "system"
},
{
"name" : "geo_IL_israel",
"rule" : "blacklist"
},
{
"name" : "geo_ME_montenegro",
"rule" : "blacklist"
},
{
"name" : "sip",
"rule" : "rbl"
},
{
"name" : "ssh",
"rule" : "rbl"
}
]
}
Response parameters
The response will be a JSON object with a key set to params. The value of this will be an array of blacklist objects, each of which contain the key attributes below.
| Field | Type | Description |
|---|---|---|
| name | String | IPDS rule name. It is used as unique identifier. |
| rule | String | It is the nature of the ipds rule. It can be blacklist, dos or rbl. |
| type | String | This field appears in dos rules and it defines if the rule is system, it applies to balancer; or farm, the rules applies to a farm. |
IPDS - Blacklists
Blacklists lets users to use lists to filter or allow traffic according to source IPs (Incomming traffic).
There are two types of lists:
- Remotes: Lists are obtained from a URL, those lists are not modificable and can be sheduled to be downloaded.
- Local: Users can create their own lists with a given policy, deny if the incomming IP matches then the traffic will be rejected or allow if the incomming IP matches then the traffic will be allowed.
This module includes preloaded lists provided by Zevenet team, the list are ready to be applied to farms. Aditionally, users can create their own personalized lists.
Several lists can be applied to the same farm, if the source IP matches in some of the list the traffic will be allowed or denied depending of the blacklist policy. At the moment the IP matches then no more black list checks are done to the source IP.
If a source IP is in two different lists, one of type deny and other of type allow, then always the allow policy is evaluated first.
List all blacklists rules
List all blacklists
Request example:
curl -k -X GET -H "ZAPI_KEY: <ZAPI_KEY_STRING>"
https://<zenlb_server>:444/zapi/v3.1/zapi.cgi/ipds/blacklists
GET /ipds/blacklists
List all blacklists created by the user or preloaded in the system that can be applied to the farms.
Response example:
{
"description" : "Get black lists",
"params" : [
{
"farms" : [],
"name" : "china",
"policy" : "deny",
"preload" : "true",
"status" : "down",
"type" : "local"
},
{
"farms" : [],
"name" : "russia",
"policy" : "deny",
"preload" : "true",
"status" : "down",
"type" : "local"
},
{
"farms" : [],
"name" : "northkorea",
"policy" : "deny",
"preload" : "true",
"status" : "down",
"type" : "local"
},
{
"farms" : [
"FarmHttp1",
"FarmGslb1",
],
"name" : "remoteList",
"policy" : "deny",
"preload" : "false",
"status" : "up",
"type" : "remote"
},
{
"farms" : [],
"name" : "myWhiteList",
"policy" : "allow",
"preload" : "false",
"status" : "down",
"type" : "local"
},
]
}
Response parameters
The response will be a JSON object with a key set to params. The value of this will be an array of blacklist objects, each of which contain the key attributes below.
| Field | Type | Description |
|---|---|---|
| farms | String[] | Farms list where the black list is applied. |
| name | String | Blacklist name. It is used as unique identifier. |
| policy | String | Action to apply to the source. The options are: deny, block the input traffic from sources of the list; or allow accept the traffic from sources of the list. |
| preload | String | The possible values are: true, the blacklist has been preloaded in the system; or false, the blacklist has been created by system administrator. |
| status | String | The possible values are: up, the blacklist is actived and blocking (or allowing) traffic of sources form the list; or down, actually the rule is not running and it is not filtering traffic. |
| type | String | Where the list is saved and who maintains it. The values are: local, the list is saved in the local system and can be modified locally, or remote, the list is downloaded from remote source through a url, It can’t be modified locally so the modifications need to be taken in the remote source. |
Retrieve a blacklist rule
Retrieve blacklist
Request example:
curl -k -X GET -H "ZAPI_KEY: <ZAPI_KEY_STRING>"
https://<zenlb_server>:444/zapi/v3.1/zapi.cgi/ipds/blacklists/loc
GET /ipds/blacklists/<name>
Show the blacklist configuration and description parameters. name is the blacklist unique identifier.
Response parameters
Response local list example:
{
"description" : "Get list loc",
"params" : {
"farms" : [],
"name" : "loc",
"policy" : "deny",
"preload" : "false",
"sources" : [
{
"id" : 0,
"source" : "192.168.0.167"
},
{
"id" : 1,
"source" : "192.168.0.186"
}
],
"status" : "up",
"type" : "local"
}
}
Local blacklist object:
| Field | Type | Description |
|---|---|---|
| farms | String[] | Farms list where the black list is applied. |
| name | String | Blacklist name. It is used as unique identifier. |
| policy | String | Action to apply to a source. The options are: deny, block the input traffic from sources of the list; or allow accept the traffic from sources of the list. |
| preload | String | The possible values are: true, the blacklist has been preloaded in the system; or false, the blacklist has been created by the system administror. |
| status | String | The possible values are: up, the blacklist is actived and blocking (or allowing) traffic of sources form the list; or down, actually the rule is not running and it is not filtering traffic. |
| type | String | Where the list is saved and who maintains it. The values are: local, the list is saved in system and maintained by system administrator; or remote, the list is downloaded from a remote url. |
| sources | Object[] | List of IPs that the list checks. Source network format accepted: Network address/Mask bit or IP |
Response remote list example:
{
"description" : "Get list remoteList",
"params" : {
"day" : "thursday",
"farms" : [
"FarmHttp1",
"FarmGslb1",
],
"frequency" : "weekly",
"name" : "remoteList",
"policy" : "deny",
"sources" : [
{
"id" : 0,
"source" : "78.12.0.4"
},
{
"id" : 1,
"source" : "68.100.15.5"
},
{
"id" : 2,
"source" : "65.12.12.95"
}
],
"time" : {
"hour" : 0,
"minutes" : 0
},
"status" : "up",
"update_status" : "This list isn't downloaded yet.",
"type" : "remote",
"url" : "http://192.168.10.10/lists/test.txt"
}
}
Remote blacklist object:
| Field | Type | Description |
|---|---|---|
| farms | String[] | Farms list where the black list is applied. |
| name | String | Black list name. It is used as unique identifier. |
| policy | String | Action to apply to a source. The options are: deny, block the input traffic from sources of the list; or allow accept the traffic from sources of the list. |
| preload | String | The possible values are: true, the blacklist has been preloaded in the system; or false, the blacklist has been created by the system administror. |
| type | String | Where the list is saved and who maintains it. The values are: local, the list is saved in system and maintained by system administrator; or remote, the list is downloaded from a remote url. |
| sources | Object[] | Ssource IPs that list checks. If the list is of type remote then the list content is not shown until the first download. |
| update_status | String | Status of the last download of the list and date of the last successful update in the local system. |
| url | String | Where the remote list is downloaded from. The remote format must be a list of one source network/bit mask or IP per line. |
| frequency | String | Remote list update frequency. The options are: daily, update all days, once or periodically, this is indicated in frequency_type field; weekly, update once in a week; or monthly, update once in a month. |
| frequency_type | String | This parameter completes the frequency daily when its value is daily. The possible values are: exact. define a hour in the day; or period, define a period time to update during the day. |
| day | String or Number | This parameter completes the parameter frequency when frecuency value is weekly or monthly. If frecuency is weekly this parameter must be aday of the week (monday, tuesday, wednesday, thursday, friday, saturday or sunday) if frequency value is monthly then this parameter must be a day of the month (a number between 1 and 31). |
| time | Object | It’s a struct which depend of the fields frequency. |
| status | String | The possible values are: up, the blacklist is actived and blocking (or allowing) traffic of sources form the list; or down, actually the rule is not running and it is not filtering traffic. |
Time object for daily frequency and period frequency_type
| Field | Type | Description |
|---|---|---|
| period | Number | How often the list is updated. |
| unit | String | Period unit. The options are: minutes, indicate the list will be updated every configured minutes; or hours, list will be updated every configured hours. |
Time object for other frequencies
| Field | Type | Description |
|---|---|---|
| hour | Number | Hour to update the list. The value must be a number between 0 and 23. |
| minutes | Number | Minutes to update the list. The value must be a number between 0 and 59. |
Sources object
| Field | Type | Description |
|---|---|---|
| id | Number | Source unique identifier in the list. |
| source | String | IP addresses or net segments that the list checks. |
Create a blacklist rule
Create a new blacklist
Request example for a local list:
curl -k -X POST -H "ZAPI_KEY: <ZAPI_KEY_STRING>" -H 'Content-Type: application/json'
-d '{"name":"newListLoc", "type":"local", "policy":"allow"}'
https://<zenlb_server>:444/zapi/v3.1/zapi.cgi/ipds/blacklists
Request example for a remote list:
curl -k -X POST -H "ZAPI_KEY: <ZAPI_KEY_STRING>" -H 'Content-Type: application/json'
-d '{"name":"newListRem", "type":"remote", "url":"https://192.168.10.12/lists/test.txt"}'
https://<zenlb_server>:444/zapi/v3.1/zapi.cgi/ipds/blacklists
POST /ipds/blacklists
Create a blacklist to be used in farms. Blacklists can be of two types:
- Local: The sources are added by the user. The list are saved locally.
- Remote: The sources are obtained from a remote location. This location is indicated by a URL. The remote list format supported is one Network address/Mask bit or IP line per line.
Request parameters
| Field | Type | Description | Required |
|---|---|---|---|
| name | String | Blacklist name. It is used as unique identifier. | true |
| type | String | Where the list is saved and who maintenances it. The values are: local, the list is saved in system and maintenance for administration system; or remote, the list is taken from an out service through a url and the administrator’s servcie will maintenance the list. | true |
| policy | String | Action to apply to a source. The options are: deny, block the input traffic from sources of the list; or allow accept the traffic from sources of the list. Default value is deny. | |
| url | String | Where the remote list is downloaded from. The remote format must be a list of one source per line in the format Network address/Mask bit or IP. | true for remote list |
{
"description" : "Post list list1",
"params" : {
"farms" : [],
"name" : "newListLoc",
"policy" : "deny",
"preload" : "false",
"type" : "local"
}
}
Response parameters
The response will be a JSON object with a key set to params. The value of this will be an array of blacklist objects, each of which contains next key attributes.
| Field | Type | Description |
|---|---|---|
| farms | String[] | Farms list where the black list is applied. |
| name | String | Blacklist name. It is used as unique identifier. |
| policy | String | Action to apply to a source. The options are: deny, block the input traffic from sources of the list; or allow accept the traffic from sources of the list. |
| preload | String | The possible values are: true, the blacklist has been preloaded in the system; or false, the blacklist has been created for system administrator. |
| type | String | Where the list is saved and who maintenances it. The values are: local, the list is saved in system and maintenance for administration system; or remote, the list is taken from an out service through a url and the administrator’s servcie will maintenance the list. |
Modify a blacklist rule
Modify a blacklist
Request example for a local list:
curl -k -X PUT -H 'Content-Type: application/json' -H "ZAPI_KEY: <ZAPI_KEY_STRING>"
-d '{"policy":"allow","source":["78.12.0.4","68.100.15.5","65.12.12.95"]}'
https://<zenlb_server>:444/zapi/v3.1/zapi.cgi/ipds/blacklists/whiteList
PUT /ipds/blacklists/<name>
Modify the configuration of a blacklist rule. name is the blacklist unique identifier.
Request parameters for a local list:
| Field | Type | Description |
|---|---|---|
| name | String | Blacklist name. It is used as unique identifier. Only it is modificabled on no preload lists. |
| policy | String | Action to apply to a source. The options are: deny, block the input traffic from sources of the list; or allow accept the traffic from sources of the list. |
| source | String[] | It is a list of IP addresses or net segments that the list checks. In order to change change only a source please see documentation section IPDS > Blacklists > Modify a source of a blacklist. Sources only are modifiabled on no preload lists. |
Response example:
{
"description" : "Modify list whiteList.",
"params" : {
"name" : "whiteList",
"policy" : "allow",
"preload" : "false",
"type" : "local"
}
}
Response parameters
The response will be a json with all requested values updated. See response example for more information.
Request example for a remote list:
curl -k -X PUT -H 'Content-Type: application/json' -H "ZAPI_KEY: <ZAPI_KEY_STRING>"
-d '{"name":"remoteList","url":"http://192.168.10.10/lists/test.txt","policy":"deny","frequency":"daily","frequency_type":"exact","time":{"hour":1,"minutes":0}}'
https://<zenlb_server>:444/zapi/v3.1/zapi.cgi/ipds/blacklists/newListRem
Request example for updating a list each 2 hours:
curl -k -X PUT -H 'Content-Type: application/json' -H "ZAPI_KEY: <ZAPI_KEY_STRING>"
-d '{"frequency":"daily","frequency_type":"period","time":{"period":2,"units":"hours"}}'
https://<zenlb_server>:444/zapi/v3.1/zapi.cgi/ipds/blacklists/newListRem
Request example for updating a list all days at 2:00 AM:
curl -k -X PUT -H 'Content-Type: application/json' -H "ZAPI_KEY: <ZAPI_KEY_STRING>"
-d '{"frequency":"daily","frequency_type":"exact","time":{"hour":2,"minutes":0}}'
https://<zenlb_server>:444/zapi/v3.1/zapi.cgi/ipds/blacklists/newListRem
Request example for updating all mondays at 0:00 AM:
curl -k -X PUT -H 'Content-Type: application/json' -H "ZAPI_KEY: <ZAPI_KEY_STRING>"
-d '{"frequency":"weekly","day":"monday","time":{"hour":0,"minutes":0}}'
https://<zenlb_server>:444/zapi/v3.1/zapi.cgi/ipds/blacklists/newListRem
Request example for updating the day 1 of the month at 12:00 PM:
curl -k -X PUT -H 'Content-Type: application/json' -H "ZAPI_KEY: <ZAPI_KEY_STRING>"
-d '{"frequency":"monthly","day":"1","time":{"hour":12,"minutes":0}}'
https://<zenlb_server>:444/zapi/v3.1/zapi.cgi/ipds/blacklists/newListRem
Request parameters for a remote list
| Field | Type | Description |
|---|---|---|
| farms | String[] | Farms list where the black list is applied. |
| name | String | Blacklist name. It is used as unique identifier. |
| policy | String | Action to apply to a source. The options are: deny, block the input traffic from sources of the list; or allow accept the traffic from sources of the list. |
| url | String | Where the remote list is downloaded from. |
| frequency | String | Remote list update frequency. The options are: daily, update all days, once or periodly, this is indicated in frequency_type field; weekly, update once in a week; or monthly, update once in a month. |
| frequency_type | String | This parameter completes the frequency daily when its value is daily. The possible values are: exact. define a hour in the day; or period, define a period time to update during the day. |
| day | String or Number | This parameter completes the frequency when its value is weekly or monthly. If it is weekly this parameter must be a week day (monday, tuesday, wednesday, thursday, friday, saturday or sunday) else if frequency is monthly then this parameter must be a month day (number between 1 and 31). |
| time | Object | It’s a struct which depend of the fields frequency. |
Time period object
These are the fields when a period time will be configurated.
It is neccessary configurating frequency with the value daily, and frequency_type with the value period.
| Field | Type | Description |
|---|---|---|
| period | Number | How often to update the list. |
| unit | String | Period unit. The options are: minutes or hours, indicate the unit of measurement for the list updates. |
Time exact hour object
These are the fields when a exact hour time will be configurated.
This object is used with the next configurations:
frequency field has the value daily and frequency_type is exact.
frequency field has the value weekly and day is the week day when the list updates.
frequency field has the value monthly and day is the number of day month when the list updates.
| Field | Type | Description |
|---|---|---|
| hour | Number | Hour to update the list. The value must be a number between 0 and 23. |
| minutes | Number | Minutes to update the list. The value must be a number between 0 and 59. |
Response example:
{
"description" : "Modify list newListRem.",
"params" : {
"day": 1,
"frequency" : "monthly",
"name" : "newListRem",
"policy" : "deny",
"preload" : "false",
"time" : {
"hour" : 12,
"minutes" : 0
},
"type" : "remote",
"update_status" : "Sync fail. Last update: 2017-02-16 14:23:00",
"url" : "https://192.168.10.12/lists/test.txt"
}
}
Response parameters
The response will be a json with all list configuration. See response example for more information.
Delete a blacklists rule
Delete a blacklists list
Request example:
curl -k -X DELETE -H "ZAPI_KEY: <ZAPI_KEY_STRING>"
https://<zenlb_server>:444/zapi/v3.1/zapi.cgi/ipds/blacklists/remoteList
DELETE /ipds/blacklists/<name>
Delete a given blacklist. name is the blacklist unique identifier.
Response example:
{
"description" : "Delete list 'remoteList'",
"message" : "The list remoteList has been deleted successful.",
"success" : "true"
}
List source from a blacklist
List source from a blacklist
Request example:
curl -k -X DELETE -H "ZAPI_KEY: <ZAPI_KEY_STRING>"
https://<zenlb_server>:444/zapi/v3.1/zapi.cgi/ipds/blacklists/localList
GET /ipds/blacklists/<name>/sources
List sources of a blacklist. name is the blacklist unique identifier.
Response example:
{
"description" : "Get localList sources",
"params" : [
{
"id" : 0,
"source" : "78.12.0.4"
},
{
"id" : 1,
"source" : "68.100.15.5"
},
{
"id" : 2,
"source" : "65.12.12.95"
}
]
}
Response parameters
The response will be a JSON with the key params and source object array as value.
Source object:
| Field | Type | Description |
|---|---|---|
| id | Number | Source unique identifier in the list. |
| source | String[] | IP addresses or net segments that the list checks. |
Add a source to a blacklist
Add a source to a blacklist
Request example:
curl -k -X POST -H "ZAPI_KEY: <ZAPI_KEY_STRING>" -H 'Content-Type: application/json'
-d '{"source":"192.168.3.1"}'
https://<zenlb_server>:444/zapi/v3.1/zapi.cgi/ipds/blacklists/localList/sources
POST /ipds/blacklists/<name>/sources
Push a new source to a blacklist. Only available for local lists and non-preloaded lists. name is the blacklist unique identifier.
Request parameters
| Field | Type | Description | Required |
|---|---|---|---|
| source | String | IP address or net segment that the list checks. | true |
Response example:
{
"description" : "Post source to localList.",
"message" : "Added 192.168.3.1 successful.",
"params" : [
{
"id" : 0,
"source" : "78.12.0.4"
},
{
"id" : 1,
"source" : "68.100.15.5"
},
{
"id" : 2,
"source" : "65.12.12.95"
},
{
"id" : 3,
"source" : "192.168.3.1"
}
]
}
Response parameters
The response will be a json with all requested values updated. See response example for more information.
Modify a source of a blacklist
Modify a source of a blacklist
Request example:
curl -k -X PUT -H "ZAPI_KEY: <ZAPI_KEY_STRING>" -H 'Content-Type: application/json'
-d '{"source":"192.168.3.1"}'
https://<zenlb_server>:444/zapi/v3.1/zapi.cgi/ipds/blacklists/localList/sources/2
PUT /ipds/blacklists/<name>/sources/<id>
Modify a source of a blacklist.
name is the blacklist unique identifier. id is the source unique identifier.
Request parameters
| Field | Type | Description | Required |
|---|---|---|---|
| source | String | IP address or net segment that the list checks. | true |
Response example:
{
"description" : "Put source into localList",
"message" : "Source 2 has been modified successful.",
"params" : {
"id" : 2,
"source" : "192.168.3.1"
}
}
Response parameters
The response will be a json with the source updated. See response example for more information.
Delete a source of a blacklist
Delete a source of a blacklist
Request example:
curl -k -X DELETE -H "ZAPI_KEY: <ZAPI_KEY_STRING>"
https://<zenlb_server>:444/zapi/v3.1/zapi.cgi/ipds/blacklists/localList/sources/2
DELETE /ipds/blacklists/<name>/sources/<id>
Remove a source from a blacklist.
name is the blacklist unique identifier. id is the source unique identifier.
Response example:
{
"description" : "Delete source from the list localList",
"message" : "Source 2 has been deleted successful.",
"success" : "true"
}
Apply an action to a blacklist rule
Apply an anction
Request example for a remote list:
curl -k -X POST -H 'Content-Type: application/json' -H "ZAPI_KEY: <ZAPI_KEY_STRING>"
-d '{"action":"update"}'
https://<zenlb_server>:444/zapi/v3.1/zapi.cgi/ipds/blacklists/remoteList/actions
POST /ipds/blacklists/<name>/actions
Apply a action to a blacklist. name is the blacklist unique identifier.
Request parameters
| Field | Type | Description | Required |
|---|---|---|---|
| action | String | Action desired to apply to a blacklist rule. The available values are: start, it actives the blaclist in all farms where it is applied; stop, it stops the blacklist for all farm where the blacklist rule is applied, the traffic won’t be blocked or allowed; update, this action only can be applied to remote blacklists, this action update the source list from the remote URL. | true |
Response example:
{
"description" : "Update a remote list",
"update" : "Sync OK. Last update: 2017-02-01 05:31:57"
}
Response parameters
The response will be a json with the download status. See response example for more information.
| Field | Type | Description | Required |
|---|---|---|---|
| update | String | Status of the last download of the list and date of the last successful update. |
IPDS - DoS
DoS protection has different type of rules, depend of the protection rule, it is applied to a different part of balancer. So there are system rules that it applies all balancer. Connection oriented rules, specific for farm working with TCP protocol. Before applying a rule to a farm, create an object with the configuration wished. Next, applied it to all farms that you need it. The system rules have the object created already and only have one possible configuration. Once configurated, enable it.
Farm DoS rules
It is necessary creates an object before to apply a rule to a farm.
limitsec
Limit of new connection per second and source. Only available in farms works with TCP protocol.
| Field | Type | Description |
|---|---|---|
| name | String | It is the object rule unique identifier. |
| limit | Number | It is the maximun number of new connections per second for a source. |
| limit_burst | Number | It is an allowed peak of new connections. A burst unit regenerates when “limit” seconds will pass. |
limitconns
Limit total current connections per source. Only available in farms works with TCP protocol.
| Field | Type | Description |
|---|---|---|
| name | String | It is the object rule unique identifier. |
| limit_conns | Number | It is the maximun number of current connection from a source. |
bogustcpflags
Check TCP protocol is respected. This rule has not configuration parameters so creating only an object you will can use in all farms. Only available in farms works with TCP protocol.
| Field | Type | Description |
|---|---|---|
| name | String | It is the object rule unique identifier. |
limitrst
Limit number of reset connection request per second. Only available in farms works with TCP protocol.
| Field | Type | Description |
|---|---|---|
| name | String | It is the object rule unique identifier. |
| limit | Number | It is the maximun number of reset request per second for a source. |
| limit_burst | Number | It is an allowed peak of reset request. A burst unit regenerates when “limit” seconds will pass. |
System DoS rules
In system DoS rules, the object has not been created.
sshbruteforce
Limit of new ssh connection.
| Field | Type | Description |
|---|---|---|
| name | String | It is the object rule unique identifier. The identifier has been defined as ssh_brute_force. |
| hits | Number | Number of hits for source before than the connections are blocked. |
| time | Number | Time in seconds to reset the hits counter. |
| status | String | The possible values are: up, the DoS rule is actived and filtering traffic; or down, the rule is not running and it is not filtering traffic. |
List all type of DoS rules
List all type of DoS rules
Request example:
curl -k -X GET -H "ZAPI_KEY: <ZAPI_KEY_STRING>"
https://<zenlb_server>:444/zapi/v3.1/zapi.cgi/ipds/dos/rules
GET /ipds/dos/rules
Show a list of DoS rules. They are not object but types to define it.
Each rule has different configuration parameters
Response example:
{
"description" : "Get DoS settings.",
"params" : {
"farm" : [
{
"description" : "Connection limit per seconds.",
"rule" : "limitsec"
},
{
"description" : "Total connections limit per source IP.",
"rule" : "limitconns"
},
{
"description" : "Check bogus TCP flags.",
"rule" : "bogustcpflags"
},
{
"description" : "Limit RST request per second.",
"rule" : "limitrst"
}
],
"system" : [
{
"description" : "SSH brute force.",
"rule" : "sshbruteforce"
},
]
}
}
Response parameters
The JSON response has two arrays farm and system. Each array item is a type of rule to apply to a farm o the system.
| Field | Type | Description |
|---|---|---|
| description | String | Briefly description of the rule. |
| rule | String | type rule unique identifier. |
List all DoS rules
List all DoS objects
Request example:
curl -k -X GET -H "ZAPI_KEY: <ZAPI_KEY_STRING>"
https://<zenlb_server>:444/zapi/v3.1/zapi.cgi/ipds/dos
GET /ipds/dos
Show configuration about all existing DoS objects.
Response example:
{
"description" : "Get DoS settings.",
"params" : [
{
"farms" : [],
"limit_conns" : 10,
"name" : "limitConnHttp",
"rule" : "limitconns",
"status" : "down",
"type" : "farm"
},
{
"farms" : [],
"limit" : 2,
"limit_burst" : 2,
"name" : "limitUsers",
"rule" : "limitsec",
"status" : "down"
"type" : "farm"
},
{
"hits" : 5,
"name" : "ssh_brute_force",
"port" : 22,
"rule" : "sshbruteforce",
"status" : "down",
"time" : 180,
"type" : "system"
},
{
"farms" : [],
"name" : "tcpAuth",
"rule" : "bogustcpflags",
"status" : "down",
"type" : "farm"
},
{
"farms" : [],
"limit" : 2,
"limit_burst" : 2,
"name" : "dos4",
"rule" : "limitrst",
"status" : "down",
"type" : "farm"
},
]
}
Response parameters
The response will be an array with all available DoS objects.
| Field | Type | Description |
|---|---|---|
| name | String | It is the object rule unique identifier. |
| rule | String | It is the type rule identifier. |
| type | String | The possible values are: farm, the rule applies to farms; or system, the rule applies to the system. |
| status | String | The possible values are: up, the DoS rule is actived and filtering traffic; or down, the rule is not running and it is not filtering traffic. |
Addionally depend of the rule, the object contains the next parameters
limitsec
| Field | Type | Description |
|---|---|---|
| farms | String[] | Farms where the rule is applied. |
| limit | Number | It is the maximun number of new connections per second for a source. |
| limit_burst | Number | It is an allowed peak of new connections. A burst unit regenerates when “limit” seconds will pass. |
limitconns
| Field | Type | Description |
|---|---|---|
| farms | String[] | Farms where the rule is applied. |
| limit_conns | Number | It is the maximun number of current connection from a source. |
bogustcpflags
| Field | Type | Description |
|---|---|---|
| farms | String[] | Farms where the rule is applied. |
limitrst
| Field | Type | Description |
|---|---|---|
| farms | String[] | Farms where the rule is applied. |
| limit | Number | It is the maximun number of reset request per second for a source. |
| limit_burst | Number | It is an allowed peak of reset request. A burst unit regenerates when “limit” seconds will pass. |
sshbruteforce
| Field | Type | Description |
|---|---|---|
| hits | Number | Number of hits for source before than the connections are blocked. |
| time | Number | Time in seconds to reset the hits counter. |
Retrieve a DoS rule
Retrieve a DoS rule
Request example for farm rule:
curl -k -X GET -H "ZAPI_KEY: <ZAPI_KEY_STRING>"
https://<zenlb_server>:444/zapi/v3.1/zapi.cgi/ipds/dos/limitConnHttp
Request example for system rule:
curl -k -X GET -H "ZAPI_KEY: <ZAPI_KEY_STRING>"
https://<zenlb_server>:444/zapi/v3.1/zapi.cgi/ipds/dos/ssh_brute_force
GET /ipds/dos/<name>
Each DoS object can have a different configuration. name is the DoS rule unique identifier.
Response example for farm rule:
{
"description" : "Get DoS limitConnHttp settings",
"params" : {
"farms" : [],
"limit_conns" : 10,
"name" : "limitConnHttp",
"rule" : "limitconns",
"status" : "down",
"type" : "farm"
}
}
Response example for system rule:
{
"description" : "Get DoS ssh_brute_force settings",
"params" : {
"hits" : 5,
"name" : "ssh_brute_force",
"port" : 22,
"rule" : "sshbruteforce",
"status" : "down",
"time" : 180,
"type" : "system"
}
}
Response parameters
The response will be an array with all available DoS objects.
| Field | Type | Description |
|---|---|---|
| name | String | It is the object rule unique identifier. |
| rule | String | It is the type rule identifier. |
| type | String | The possible values are: farm, the rule applies to farms; or system, the rule applies to the system. |
| status | String | The possible values are: up, the DoS rule is actived and filtering traffic; or down, the rule is not running and it is not filtering traffic. |
Addionally depend of the rule, the object contains the next parameters
limitsec
| Field | Type | Description |
|---|---|---|
| farms | String[] | Farms where the rule is applied. |
| limit | Number | It is the maximun number of new connections per second for a source. |
| limit_burst | Number | It is an allowed peak of new connections. A burst unit regenerates when “limit” seconds will pass. |
limitconns
| Field | Type | Description |
|---|---|---|
| farms | String[] | Farms where the rule is applied. |
| limit_conns | Number | It is the maximun number of current connection from a source. |
bogustcpflags
| Field | Type | Description |
|---|---|---|
| farms | String[] | Farms where the rule is applied. |
limitrst
| Field | Type | Description |
|---|---|---|
| farms | String[] | Farms where the rule is applied. |
| limit | Number | It is the maximun number of reset request per second for a source. |
| limit_burst | Number | It is an allowed peak of reset request. A burst unit regenerates when “limit” seconds will pass. |
sshbruteforce
| Field | Type | Description |
|---|---|---|
| hits | Number | Number of hits for source before than the connections are blocked. |
| time | Number | Time in seconds to reset the hits counter. |
Create a DoS rule
Create a DoS rule
Request example:
curl -k -X POST -H 'Content-Type: application/json' -H "ZAPI_KEY: <ZAPI_KEY_STRING>"
-d '{"name":"limitUsers", "rule":"limitsec"}'
https://<zenlb_server>:444/zapi/v3.1/zapi.cgi/ipds/dos
POST /ipds/dos
Create a DoS object to use it in as farms as it is necessary.
Each DoS object can have a different configuration.
Request parameters
| Field | Type | Description | Required |
|---|---|---|---|
| name | String | It is the object rule unique identifier. | true |
| rule | String | It is the type rule identifier. The options are: limitconns, limitsec, limitrst or bogustcpflags. | true |
Response example:
{
"description" : "Post a DoS rule",
"params" : {
"farms" : [],
"limit" : 2,
"limit_burst" : 2,
"name" : "limitUsers",
"rule" : "limitsec",
"type" : "farm"
}
}
Response parameters
The response will be a json with the default configuration for the created rule. See response example for more information.
Modify a DoS rule
Modify a DoS rule
Request example:
curl -k -X PUT -H 'Content-Type: application/json' -H "ZAPI_KEY: <ZAPI_KEY_STRING>"
-d '{"hits":"10","status":"up","time":"100"}'
https://<zenlb_server>:444/zapi/v3.1/zapi.cgi/ipds/dos/ssh_brute_force
PUT /ipds/dos/<name>
Modify a DoS rule. name is the DoS rule unique identifier.
Request parameters
Each type of rule can be different parameters. The modifiable parameters are the next:
limitsec
| Field | Type | Description |
|---|---|---|
| limit | Number | It is the maximun number of new connections per second for a source. |
| limit_burst | Number | It is an allowed peak of new connections. A burst unit regenerates when “limit” seconds will pass. |
limitconns
| Field | Type | Description |
|---|---|---|
| limit_conns | Number | It is the maximun number of current connection from a source. |
bogustcpflags
No have parameters.
limitrst
| Field | Type | Description |
|---|---|---|
| limit | Number | It is the maximun number of reset request per second for a source. |
| limit_burst | Number | It is an allowed peak of reset request. A burst unit regenerates when “limit” seconds will pass. |
sshbruteforce
| Field | Type | Description |
|---|---|---|
| hits | Number | Number of hits for source before than the connections are blocked. |
| time | Number | Time in seconds to reset the hits counter. |
Response example:
{
"description" : "Put DoS rule settings",
"params" : {
"hits" : 10,
"name" : "ssh_brute_force",
"port" : 22,
"rule" : "sshbruteforce",
"status" : "up",
"time" : 100,
"type" : "system"
},
"success" : "true"
}
Response parameters
The response will be a json with all requested values updated. See response example for more information.
Delete a DoS rule
Delete a DoS rule
Request example:
curl -k -X DELETE -H "ZAPI_KEY: <ZAPI_KEY_STRING>"
https://<zenlb_server>:444/zapi/v3.1/zapi.cgi/ipds/dos/limitConnHttp
DELETE /ipds/dos/<name>
System rules can not be delete it. To disable it, put the status to down. name is the DoS rule unique identifier.
Response example:
{
"description" : "Delete DoS rule",
"message" : "Deleted limitConnHttp successful.",
"success" : "true"
}
Apply an anction to a DoS rule
Apply an anction
Request example for a remote list:
curl -k -X POST -H 'Content-Type: application/json' -H "ZAPI_KEY: <ZAPI_KEY_STRING>"
-d '{"action":"start"}'
https://<zenlb_server>:444/zapi/v3.1/zapi.cgi/ipds/dos/conns_maximum/actions
POST /ipds/dos/<name>/actions
Apply a action to a dos rule. name is the dos rule unique identifier.
Request parameters
| Field | Type | Description | Required |
|---|---|---|---|
| action | String | Action desired to apply to a DoS rule. The available values are: start, it actives the DoS rule in all farms where it is applied; stop, it disactives the DoS for all farm where the DoS rule is applied, the traffic won’t be blocked or allowed; restart, reset a DoS rule for all its farms. | true |
Response example:
{
"description" : "Apply a action to a DoS rule",
"params" : {
"action" : "start"
}
}
Response parameters
If there are no issues in the configuration then zapi will return the requested action.
IPDS - RBL
RBL, Realtime blackhole lists lets create a security system delegating, the tedious task of maintenance an updated security system, to a speclialist. RBL checks load balancer input traffic in an extern database through DNS protocol. The DNS server owner is the responsible of updating and providing a quality sources. The input traffic from an IP source that is in the DNS database will be dropped.
To work with RBL service, first DNS domains will be added, each DNS domain is contained a specific providor list that sorts the source for different criterion as type of realized attack or severity of an attack.
Once the DNS domains have been created, it is necessary to create a RBL rule with the rule configuration. Then linking DNS domains with the RBL rule. Each rule can examine different domains.
Last apply the RBL rule to all desired farms.
List all RBL rules
List all RBL rules
Request example:
curl -k -X GET -H "ZAPI_KEY: <ZAPI_KEY_STRING>"
https://<zenlb_server>:444/zapi/v3.1/zapi.cgi/ipds/rbl
GET /ipds/rbl
List all RBL rules available in the load balancer.
Response example:
{
"description" : "Get RBL rules",
"params" : [
{
"cache_size" : 8192,
"cache_time" : 3600,
"domains" : [
"ssh.rbl.zevenet.com",
"ssh.blocklist.de"
],
"farms" : [
"sshL4farm"
],
"local_traffic" : "false",
"log_level" : 4,
"name" : "protection_ssh",
"only_logging" : "true",
"queue_size" : 64538,
"status" : "down",
"threadmax" : 700
},
{
"cache_size" : 2048,
"cache_time" : 7200,
"domains" : [],
"farms" : [],
"local_traffic" : "true",
"log_level" : 4,
"name" : "sip",
"only_logging" : "true",
"queue_size" : 32269,
"status" : "down",
"threadmax" : 400
},
{
"cache_size" : 8192,
"cache_time" : 3600,
"domains" : [],
"farms" : [
"webAPP"
],
"local_traffic" : "false",
"log_level" : 4,
"name" : "web_attacks",
"only_logging" : "true",
"queue_size" : 64538,
"status" : "down",
"threadmax" : 700
}
]
}
Response parameters
The response will be a JSON object with a key set to params. The value of this will be an array of RBL objects, each of which contain the key attributes below.
| Field | Type | Description |
|---|---|---|
| cache_size | Number | It is the number of IP source that the RBL rule can cache. |
| cache_time | Number | It is the time (in seconds) that an IP source will be blocked. |
| domains | String[] | It is a list with all the domains that the rule is querying. |
| farms | String[] | Farms list where the black list is applied. |
| local_traffic | String | If this field has the value true, the RBL rule will examine traffic from private network segments; or if its value is false the RBL rule will ignore traffic from private network segments. The local traffic never will be blocked by a public DNS. |
| log_level | Number | It is the severity log level. It can have a value between 0 and 7, being 0 emergency and 7 debug. |
| name | String | RBL rule name. It is used as unique identifier. |
| only_logging | String | If the value is true, when a IP matches in a domain, it will be logged; or if this field has the value false, when a IP matches in a domain, the IP will be logged and the packet will be dropped. |
| queue_size | Number | It is the number of packet that the rule can keep in the queue. |
| status | String | Show the RBL rule status. Its value can be down, if the rule is not working; or up it the rule is working. |
| threadmax | String | It it the number of packet that the rule can query simultaneously to DNS servers. Its maximum value is 700. When the number of input packets is bigger than threadmax, the next packets will be automatically accepted. |
Retrieve a RBL rule
Retrieve RBL rule
Request example:
curl -k -X GET -H "ZAPI_KEY: <ZAPI_KEY_STRING>"
https://<zenlb_server>:444/zapi/v3.1/zapi.cgi/ipds/rbl/protection_ssh
GET /ipds/rbl/<name>
Show the RBL configuration and its description parameters. name is the RBL rule unique identifier.
Response parameters
Response example:
{
"description" : "Get RBL protection_ssh",
"params" : {
"cache_size" : 8192,
"cache_time" : 3600,
"domains" : [
"ssh.zevenet.com",
"ssh.blocklist.de"
],
"farms" : [
"sshL4farm"
],
"local_traffic" : "false",
"log_level" : 4,
"name" : "protection_ssh",
"only_logging" : "true",
"queue_size" : 64538,
"status" : "down",
"threadmax" : 700
}
}
RBL rule object:
| Field | Type | Description |
|---|---|---|
| cache_size | Number | It is the number of IP source that the RBL rule can cache. |
| cache_time | Number | It is the time (in seconds) that an IP source will be blocked. |
| domains | String[] | It is a list with all the domains that the rule is querying. |
| farms | String[] | Farms list where the black list is applied. |
| local_traffic | String | If this field has the value true, the RBL rule will examine traffic from private network segments; or if its value is false the RBL rule will ignore traffic from private network segments. The local traffic never will be blocked by a public DNS. |
| log_level | Number | It is the severity log level. It can have a value between 0 and 7, being 0 emergency and 7 debug. |
| name | String | RBL rule name. It is used as unique identifier. |
| only_logging | String | If the value is true, when a IP matches in a domain, it will be logged; or if this field has the value false, when a IP matches in a domain, the IP will be logged and the packet will be dropped. |
| queue_size | Number | It is the number of packet that the rule can keep in the queue. |
| status | String | Show the RBL rule status. Its value can be down, if the rule is not working; or up it the rule is working. |
| threadmax | String | It it the number of packet that the rule can query simultaneously to DNS servers. Its maximum value is 700. When the number of input packets is bigger than threadmax, the next packets will be automatically accepted. |
Create a RBL rule
Create a new RBL rule
Request example:
curl -k -X POST -H "ZAPI_KEY: <ZAPI_KEY_STRING>" -H 'Content-Type: application/json'
-d '{"name":"all"}'
https://<zenlb_server>:444/zapi/v3.1/zapi.cgi/ipds/rbl
POST /ipds/rbl
Create a RBL rule to be used in farms.
Request parameters
| Field | Type | Description | Required |
|---|---|---|---|
| name | String | RBL rule name. It is used as unique identifier. | true |
{
"description" : "Create a RBL rule.",
"params" : {
"cache_size" : 8192,
"cache_time" : 3600,
"domains" : [],
"farms" : [],
"local_traffic" : "false",
"log_level" : 4,
"name" : "all",
"only_logging" : "true",
"queue_size" : 64538,
"status" : "down",
"threadmax" : 700
}
}
Response parameters
The response will be a JSON object with a key set to params. The value of this will be an array of RBL objects, each of which contains next key attributes.
| Field | Type | Description |
|---|---|---|
| cache_size | Number | It is the number of IP source that the RBL rule can cache. |
| cache_time | Number | It is the time (in seconds) that an IP source will be blocked. |
| domains | String[] | It is a list with all the domains that the rule is querying. |
| farms | String[] | Farms list where the black list is applied. |
| local_traffic | String | If this field has the value true, the RBL rule will examine traffic from private network segments; or if its value is false the RBL rule will ignore traffic from private network segments. The local traffic never will be blocked by a public DNS. |
| log_level | Number | It is the severity log level. It can have a value between 0 and 7, being 0 emergency and 7 debug. |
| name | String | RBL rule name. It is used as unique identifier. |
| only_logging | String | If the value is true, when a IP matches in a domain, it will be logged; or if this field has the value false, when a IP matches in a domain, the IP will be logged and the packet will be dropped. |
| queue_size | Number | It is the number of packet that the rule can keep in the queue. |
| status | String | Show the RBL rule status. Its value can be down, if the rule is not working; or up it the rule is working. |
| threadmax | String | It it the number of packet that the rule can query simultaneously to DNS servers. Its maximum value is 700. When the number of input packets is bigger than threadmax, the next packets will be automatically accepted. |
Modify a RBL rule
Modify a RBL rule
Request example:
curl -k -X PUT -H 'Content-Type: application/json' -H "ZAPI_KEY: <ZAPI_KEY_STRING>"
-d '{"name":"all_reported","cache_size":16384, "cache_time":180000, "queue_size":32269, "threadmax":500, "local_traffic":"true", "log_level":4, "only_logging":"true"}'
https://<zenlb_server>:444/zapi/v3.1/zapi.cgi/ipds/rbl/all
PUT /ipds/rule/<name>
Modify the configuration of a RBL rule. name is the RBL rule unique identifier.
Request parameters:
| Field | Type | Description |
|---|---|---|
| cache_size | Number | It is the number of IP source that the RBL rule can cache. |
| cache_time | Number | It is the time (in seconds) that an IP source will be blocked. |
| local_traffic | String | If this field has the value true, the RBL rule will examine traffic from private network segments; or if its value is false the RBL rule will ignore traffic from private network segments. The local traffic never will be blocked by a public DNS. |
| log_level | Number | It is the severity log level. It can have a value between 0 and 7, being 0 emergency and 7 debug. |
| name | String | RBL rule name. It is used as unique identifier. |
| only_logging | String | If the value is true, when a IP matches in a domain, it will be logged; or if this field has the value false, when a IP matches in a domain, the IP will be logged and the packet will be dropped. |
| queue_size | Number | It is the number of packet that the rule can keep in the queue. |
| threadmax | String | It it the number of packet that the rule can query simultaneously to DNS servers. Its maximum value is 700. When the number of input packets is bigger than threadmax, the next packets will be automatically accepted. |
Response example:
{
"description" : "Modify RBL rule all.",
"params" : {
"cache_size" : 16384,
"cache_time" : 180000,
"domains" : [],
"farms" : [],
"local_traffic" : "true",
"log_level" : 4,
"name" : "all",
"only_logging" : "true",
"queue_size" : 32269,
"status" : "down",
"threadmax" : 500
}
}
Response parameters
The response will be a JSON object with a key set to params. The value of this will be an array of RBL objects, each of which contains next key attributes.
| Field | Type | Description |
|---|---|---|
| cache_size | Number | It is the number of IP source that the RBL rule can cache. |
| cache_time | Number | It is the time (in seconds) that an IP source will be blocked. |
| domains | String[] | It is a list with all the domains that the rule is querying. |
| farms | String[] | Farms list where the black list is applied. |
| local_traffic | String | If this field has the value true, the RBL rule will examine traffic from private network segments; or if its value is false the RBL rule will ignore traffic from private network segments. The local traffic never will be blocked by a public DNS. |
| log_level | Number | It is the severity log level. It can have a value between 0 and 7, being 0 emergency and 7 debug. |
| name | String | RBL rule name. It is used as unique identifier. |
| only_logging | String | If the value is true, when a IP matches in a domain, it will be logged; or if this field has the value false, when a IP matches in a domain, the IP will be logged and the packet will be dropped. |
| queue_size | Number | It is the number of packet that the rule can keep in the queue. |
| status | String | Show the RBL rule status. Its value can be down, if the rule is not working; or up it the rule is working. |
| threadmax | String | It it the number of packet that the rule can query simultaneously to DNS servers. Its maximum value is 700. When the number of input packets is bigger than threadmax, the next packets will be automatically accepted. |
Copy a RBL rule
Copy a RBL rule
Request example:
curl -k -X POST -H 'Content-Type: application/json' -H "ZAPI_KEY: <ZAPI_KEY_STRING>"
-d '{"name":"copied_rule"}'
https://<zenlb_server>:444/zapi/v3.1/zapi.cgi/ipds/rbl/all_reported
POST /ipds/rule/<name>
Copy a RBL rule to create a new rule. name is the RBL rule unique identifier.
Request parameters:
| Field | Type | Description | required |
|---|---|---|---|
| name | String | RBL rule name for the new rule. It is used as unique identifier. | true |
Response example:
{
"description" : "Copy a RBL rule.",
"params" : {
"cache_size" : 16384,
"cache_time" : 180000,
"domains" : [],
"farms" : [],
"local_traffic" : "true",
"log_level" : 4,
"name" : "copied_rule",
"only_logging" : "true",
"queue_size" : 32269,
"status" : "down",
"threadmax" : 500
}
}
Response parameters
The response will be a JSON object with a key set to params. The value of this will be an array of RBL objects, each of which contains next key attributes.
| Field | Type | Description |
|---|---|---|
| cache_size | Number | It is the number of IP source that the RBL rule can cache. |
| cache_time | Number | It is the time (in seconds) that an IP source will be blocked. |
| domains | String[] | It is a list with all the domains that the rule is querying. |
| farms | String[] | Farms list where the black list is applied. |
| local_traffic | String | If this field has the value true, the RBL rule will examine traffic from private network segments; or if its value is false the RBL rule will ignore traffic from private network segments. The local traffic never will be blocked by a public DNS. |
| log_level | Number | It is the severity log level. It can have a value between 0 and 7, being 0 emergency and 7 debug. |
| name | String | RBL rule name. It is used as unique identifier. |
| only_logging | String | If the value is true, when a IP matches in a domain, it will be logged; or if this field has the value false, when a IP matches in a domain, the IP will be logged and the packet will be dropped. |
| queue_size | Number | It is the number of packet that the rule can keep in the queue. |
| status | String | Show the RBL rule status. Its value can be down, if the rule is not working; or up it the rule is working. |
| threadmax | String | It it the number of packet that the rule can query simultaneously to DNS servers. Its maximum value is 700. When the number of input packets is bigger than threadmax, the next packets will be automatically accepted. |
Delete a RBL rule
Delete a RBL
Request example:
curl -k -X DELETE -H "ZAPI_KEY: <ZAPI_KEY_STRING>"
https://<zenlb_server>:444/zapi/v3.1/zapi.cgi/ipds/rbl/sip
DELETE /ipds/rbl/<name>
Delete a given RBL rule. name is the RBL rule unique identifier.
Response example:
{
"description" : "Delete RBL 'sip'",
"message" : "The rule sip has been deleted successful.",
"success" : "true"
}
List all the RBL domains
List all the RBL domains
Request example:
curl -k -X GET -H "ZAPI_KEY: <ZAPI_KEY_STRING>"
https://<zenlb_server>:444/zapi/v3.1/zapi.cgi/ipds/rbl/domains
GET /ipds/rbl/domains
List all availabled domains to link with RBL rules.
Response example:
{
"description" : "Get RBL domains",
"params" : {
"preloaded" : [
{
"domain" : "all.rbl.zevenet.com",
"id" : 0
},
{
"domain" : "ssh.rbl.zevenet.com",
"id" : 1
},
{
"domain" : "sip.rbl.zevenet.com",
"id" : 2
}
],
"user" : [
{
"domain" : "zen.spamhaus.org",
"id" : 0
},
{
"domain" : "web.dnsbl.sorbs.net",
"id" : 1
}
]
}
}
Response parameters
The response will be a JSON with the key params and two type of domains list as value.
Source object:
| Field | Type | Description |
|---|---|---|
| preloaded | Object[] | It is a list with the domains added by Zevenet team. |
| user | Object[] | It is a list with the domains added by the load balancer administrator. |
preloaded and user object:
| Field | Type | Description |
|---|---|---|
| id | Number[] | It is the id that identifier a domain. |
| domain | String[] | It is the domain where the rbl rule does queries. |
Add a domain
Add a domain
Request example:
curl -k -X POST -H "ZAPI_KEY: <ZAPI_KEY_STRING>" -H 'Content-Type: application/json'
-d '{"domain":"web.dnsbl.sorbs.net"}'
https://<zenlb_server>:444/zapi/v3.1/zapi.cgi/ipds/rbl/domains
POST /ipds/rbl/domains
Add a new domain to the user domain list.
Request parameters
| Field | Type | Description | Required |
|---|---|---|---|
| domain | String | It is a zone of a RBL providor where a RBL rule will do queries. | true |
Response example:
{
"description" : "Post a RBL domain.",
"message" : "",
"params" : {
"domains" : [
"zen.spamhaus.org",
"sip.blocklist.de",
"web.dnsbl.sorbs.net"
]
}
}
Response parameters
The response will be a json with a list of all domains added by load balancer administrator.
| Field | Type | Description |
|---|---|---|
| domains | String[] | It is a list with the domains added by the load balancer administrator. |
Modify a domain
Modify a domain
Request example:
curl -k -X PUT -H "ZAPI_KEY: <ZAPI_KEY_STRING>" -H 'Content-Type: application/json'
-d '{"domain":"ssh.blocklist.de"}'
https://<zenlb_server>:444/zapi/v3.1/zapi.cgi/ipds/rbl/domains/2
PUT /ipds/rbl/domains/<id>
Modify a domain or the user domain list by other that is sent as parameter.
id is the domain user identifier.
Request parameters
| Field | Type | Description |
|---|---|---|
| domain | String | It is a domain that it replaces the domain sent in the URI. |
Response example:
{
"description" : "Replace a domain",
"message" : "RBL domain ssh.blocklist.de has been modified successful.",
"params" : {
"domains" : [
{
"domain" : "zen.spamhaus.org",
"id" : 0
},
{
"domain" : "web.dnsbl.sorbs.net",
"id" : 1
},
{
"domain" : "ssh.blocklist.de",
"id" : 2
}
]
}
}
Response parameters
The response will be a json with a list of all domains added by load balancer administrator.
User domain object:
| Field | Type | Description |
|---|---|---|
| id | Number[] | It is the id that identifier a domain. |
| domain | String[] | It is the domain where the rbl rule does queries. |
Delete a domain
Delete a domain
Request example:
curl -k -X DELETE -H "ZAPI_KEY: <ZAPI_KEY_STRING>"
https://<zenlb_server>:444/zapi/v3.1/zapi.cgi/ipds/rbl/domains/1
DELETE /ipds/rbl/domains/<id>
Delete a domain from the user domain list.
id is the domain user identifier that it will be deleted.
Response example:
{
"description" : "Delete a RBL domain.",
"message" : "RBL domain web.dnsbl.sorbs.net has been deleted successful.",
"success" : "true"
}
Apply an action in a RBL rule
Apply an action
Request example:
curl -k -X POST -H 'Content-Type: application/json' -H "ZAPI_KEY: <ZAPI_KEY_STRING>"
-d '{"action":"stop"}' https://<zevenet_server>:444/zapi/v3.1/zapi.cgi/ipds/rbl/<name>/action
POST ipds/rbl/<name>/actions
Apply an action to a RBL farm, see the Request parameters table for actions. To apply an action to a rule it is necessary that the rule is applied almost to one farm.
name is the RBL rule unique identifier.
Request parameters
| Field | Type | Description |
|---|---|---|
| action | String | Apply the action desired. The actions are: stop, the RBL rule will be stopped and the traffic forward farms where it is applied the rule will not be dropped. start, the RBL rule will be started and all traffic forward the farms where this rule is applied will be dropped. |
Response example:
{
"description" : "Apply a action to a RBL rule",
"params" : {
"action" : "start"
}
}
Response parameters
If there are no issues in the configuration then zapi will return the requested action.
System
System options offer you the possibility of personalizate the services running in the balancer and the global parameters.
Show version
Show version
Request example:
curl -k -X GET -H "ZAPI_KEY: <ZAPI_KEY_STRING>"
https://<zevenet_server>:444/zapi/v3.1/zapi.cgi/system/version
GET /system/version
Show informacion about the product version.
Response example:
{
"description" : "Get version",
"params" : {
"appliance_version" : "ZVA 4100, hypervisor: xen",
"hostname" : "DEV5",
"kernel_version" : "3.16.7-ckt20",
"system_date" : "Thu Feb 2 10:34:27 2017",
"zevenet_version" : "5.0"
}
}
Response parameters
The response will be a JSON object with the below parameters.
| Field | Type | Description |
|---|---|---|
| appliance_version | String | Applicance version. Show also hypervisor if is a virtual machine. |
| hostname | String | Host name. |
| kernel_version | String | Linux kernel version. |
| system_date | String | System date. |
| zevenet_version | String | Zevenet version. |
Show DNS
Show DNS
Request example:
curl -k -X GET -H "ZAPI_KEY: <ZAPI_KEY_STRING>"
https://<zevenet_server>:444/zapi/v3.1/zapi.cgi/system/dns
GET /system/dns
Show the DNS service configuration.
Response example:
{
"description" : "Get dns",
"params" : {
"primary" : "8.8.8.8",
"secondary" : null
}
}
Response parameters
The response will be a JSON object with the below parameters.
| Field | Type | Description |
|---|---|---|
| primary | String | Primary DNS configurated in system. |
| secondary | String | Secondary DNS configurated in system. |
Modify DNS
Modify DNS
Request example:
curl -k -X POST -H 'Content-Type: application/json' -H "ZAPI_KEY: <ZAPI_KEY_STRING>"
-d '{"primary":"8.8.4.4","secondary":"8.8.8.8"}'
https://<zevenet_server>:444/zapi/v3.1/zapi.cgi/system/dns
POST /system/dns
Modify the DNS service configuration.
Request parameters
| Field | Type | Description |
|---|---|---|
| primary | String | Primary DNS configurated in system. |
| secondary | String | Secondary DNS configurated in system. |
Response example:
{
"description" : "Post dns",
"params" : {
"primary" : "8.8.4.4",
"secondary" : "8.8.8.8"
}
}
Response parameters
The response will be a json with all requested values updated. See response example for more information.
Show SSH
Show SSH
Request example:
curl -k -X GET -H "ZAPI_KEY: <ZAPI_KEY_STRING>"
https://<zevenet_server>:444/zapi/v3.1/zapi.cgi/system/ssh
GET /system/ssh
Show the SSH service configuration.
Response example:
{
"description" : "Get ssh",
"params" : {
"listen" : "*",
"port" : "22"
}
}
Response parameters
| Field | Type | Description |
|---|---|---|
| listen | String | IP of system where SSH service is listening. The character * is used to listen in all configurated IPs .<$ |
| port | String | Port configurated for SSH service. |
Modify SSH
Modify SSH
Request example:
curl -k -X POST -H 'Content-Type: application/json' -H "ZAPI_KEY: <ZAPI_KEY_STRING>"
-d '{"listen":"192.168.100.241","port":"22"}'
https://<zevenet_server>:444/zapi/v3.1/zapi.cgi/system/ssh
POST /system/ssh
Modify the SSH service configuration.
Request parameters
The response will be a JSON object with the below parameters.
| Field | Type | Description |
|---|---|---|
| listen | String | IP of system where SSH service is listening. The character * is used to listen in all configurated IPs. |
| port | String | Port configurated for SSH service. |
Response example:
{
"description" : "Post ssh",
"params" : {
"listen" : "192.168.100.241",
"port" : "22"
}
}
Response parameters
The response will be a json with all requested values updated. See response example for more information.
Show SNMP
Show SNMP
Request example:
curl -k -X GET -H "ZAPI_KEY: <ZAPI_KEY_STRING>"
https://<zevenet_server>:444/zapi/v3.1/zapi.cgi/system/snmp
GET /system/snmp
Show the SNMP service configuration.
Response example:
{
"description" : "Get snmp",
"params" : {
"community" : "public",
"ip" : "*",
"port" : "161",
"scope" : "0.0.0.0/0",
"status" : "false"
}
}
Response parameters
The response will be a JSON object with the below parameters.
| Field | Type | Description |
|---|---|---|
| community | String | Community name. Read Only Community used. |
| ip | String | Interface IP where the SNMP service is running. It’s safe to keep the All interfaces enabled using the character *. |
| port | String | Port where SNMP service is running. |
| scope | String | IP or subnet with access (IP/bit). Allowed client IPs to acces SNMPD service, in case you want to allow access only one IP please use the bit “/32”. |
| status | String | Status of SNMP service. The possible values are: true, the service is running; or false, the service is stopped. |
Modify SNMP
Modify SNMP
Request example:
curl -k -X POST -H 'Content-Type: application/json' -H "ZAPI_KEY: <ZAPI_KEY_STRING>"
-d '{"ip":"192.168.100.241","port":"170","scope":"0.0.0.0/0","status":"true","community":"public"}'
https://<zevenet_server>:444/zapi/v3.1/zapi.cgi/system/snmp
POST /system/snmp
Modify the SNMP service configuration.
Request parameters
| Field | Type | Description |
|---|---|---|
| community | String | Community name. Read Only Community used. |
| ip | String | Interface IP where the SNMP service is running. It’s safe to keep the All interfaces enabled using the character *. |
| port | String | Port where SNMP service is running. |
| scope | String | IP or subnet with access (IP/bit). Allowed client IPs to acces SNMPD service, in case you want to allow access only one IP please use the bit “/32”. |
| status | String | Status of SNMP service. The possible values are: true, the service is running; or false, the service is stopped. |
Response example:
{
"description" : "Post snmp",
"params" : {
"community" : "public",
"ip" : "192.168.100.241",
"port" : "170",
"scope" : "0.0.0.0/0",
"status" : "true"
}
}
Response parameters
The response will be a json with all requested values updated. See response example for more information.
Retrieve license
Retrieve license
Request example:
curl -k -X GET -H "ZAPI_KEY: <ZAPI_KEY_STRING>"
https://<zevenet_server>:444/zapi/v3.1/zapi.cgi/system/license/txt
GET /system/license/<format>
Show the Zevenet license in a format. The available format values are html or txt.
Show NTP
Show NTP
Request example:
curl -k -X GET -H "ZAPI_KEY: <ZAPI_KEY_STRING>"
https://<zevenet_server>:444/zapi/v3.1/zapi.cgi/system/ntp
GET /system/ntp
Show the NTP service configuration.
Response example:
{
"description" : "Get ntp",
"params" : {
"server" : "pool.ntp.org"
}
}
Response parameters
The response will be a JSON object with the below parameters.
| Field | Type | Description |
|---|---|---|
| server | String | Server where NTP client does the requests. |
Modify NTP
Modify NTP
Request example:
curl -k -X POST -H 'Content-Type: application/json' -H "ZAPI_KEY: <ZAPI_KEY_STRING>"
-d '{"server":"pool.ntp.org"}'
https://<zevenet_server>:444/zapi/v3.1/zapi.cgi/system/ntp
POST /system/ntp
Modify the NTP service configuration.
Request parameters
| Field | Type | Description |
|---|---|---|
| server | String | Server where NTP client does the requests. |
Response example:
{
"description" : "Post ntp",
"params" : "pool.ntp.org"
}
Response parameters
The response will be a json with all requested values updated. See response example for more information.
Show HTTP server
Show HTTP server
Request example:
curl -k -X GET -H "ZAPI_KEY: <ZAPI_KEY_STRING>"
https://<zevenet_server>:444/zapi/v3.1/zapi.cgi/system/http
GET /system/http
Show the HTTP service configuration. It is where Zevenet API and GUI are running.
Response example:
{
"description" : "Get http",
"params" : {
"ip" : "*",
"port" : "444"
}
}
Response parameters
The response will be a JSON object with the below parameters.
| Field | Type | Description |
|---|---|---|
| ip | String | IP where HTTP server is listening. The character * is used to listen in all configurated IPs. |
| port | String | Port where HTTP service is listening. |
Modify HTTP server
Modify HTTP server
Request example:
curl -k -X POST -H 'Content-Type: application/json' -H "ZAPI_KEY: <ZAPI_KEY_STRING>"
-d '{"ip":"192.168.100.241","port":"80"}'
https://<zevenet_server>:444/zapi/v3.1/zapi.cgi/system/http
POST /system/http
Modify the HTTP service configuration.
Request parameters
| Field | Type | Description |
|---|---|---|
| ip | String | IP where HTTP server is listening. The character * is used to listen in all configurated IPs. |
| port | String | Port where HTTP service is listening. |
Response example:
{
"description" : "Post http",
"params" : {
"ip" : "192.168.100.241",
"port" : "80"
}
}
Response parameters
The response will be a json with all requested values updated. See response example for more information.
List all users
List all users
Request example:
curl -k -X GET -H "ZAPI_KEY: <ZAPI_KEY_STRING>"
https://<zevenet_server>:444/zapi/v3.1/zapi.cgi/system/users
GET /system/users
List the available users in the system.
Response example:
{
"description" : "Get users",
"params" : [
{
"status" : "true",
"user" : "root"
},
{
"status" : "true",
"user" : "zapi"
}
]
}
Response parameters
The response will be a JSON object with an array of the below parameters.
| Field | Type | Description |
|---|---|---|
| status | String | User status. The possible values are: true, the user is activated; or not false, the user is desactivated. |
| user | String | User name. |
Retrieve zapi user
Retrieve zapi user
Request example:
curl -k -X GET -H "ZAPI_KEY: <ZAPI_KEY_STRING>"
https://<zevenet_server>:444/zapi/v3.1/zapi.cgi/system/users/zapi
GET /system/users/zapi
Show the zapi user configuration. This parameters are neccessary to access to Zevenet services through zapi.
Response example:
{
"description" : "Zapi user configuration.",
"params" : {
"key" : "root",
"status" : "true"
}
}
Response parameters
The response will be a JSON object with an array of the below parameters.
| Field | Type | Description |
|---|---|---|
| key | String | Key to authenticate in zapi. This is the parameter ZAPI_KEY used in calls to the zapi. |
| status | String | Zapi user status. If its value is true, it is possible to use the zapi; or not false, the zapi is desactivated and it is not possible send it request. |
Modify zapi user configuration
Modify zapi user configuration
Request example:
curl -k -X POST -H 'Content-Type: application/json' -H "ZAPI_KEY: <ZAPI_KEY_STRING>"
-d '{"key":"newzapikey","status":"enable","newpassword":"password1234"}'
https://<zevenet_server>:444/zapi/v3.1/zapi.cgi/system/users/zapi
POST /system/users/zapi
Modify the zapi user configuration. This parameters are neccessary to access to Zevenet services through zapi.
Request parameters
| Field | Type | Description |
|---|---|---|
| key | String | Key to authenticate in zapi. This is the parameter ZAPI_KEY used in calls to the zapi. |
| newpassword | String | New password for zapi user. |
| status | String | Zapi user status. If its value is true, it is possible to use the zapi; or not false, the zapi is desactivated and it is not possible send it request. |
Response example:
{
"description" : "Zapi user settings.",
"message" : "Settings was changed successful.",
"params" : {
"key" : "newzapikey",
"newpassword" : "password1234",
"status" : "enable"
}
}
Response parameters
The response will be a json with all requested values updated. See response example for more information.
Modify root password
Modify root password
Request example:
curl -k -X POST -H 'Content-Type: application/json' -H "ZAPI_KEY: <ZAPI_KEY_STRING>"
{"password":"admin","newpassword":"alwaysisbetterastrongpass"}
https://<zevenet_server>:444/zapi/v3.1/zapi.cgi/system/users/root
POST /system/users/root
Modify the root password. This user is used to access to zevenet services through GUI
Request parameters
| Field | Type | Description | Required |
|---|---|---|---|
| password | String | Current root user password. | true |
| newpassword | String | New password for root user. | true |
Response example:
{
"description" : "User settings.",
"message" : "Settings was changed succesful.",
"params" : {
"newpassword" : "alwaysisbetterastrongpass",
"password" : "admin"
}
}
Response parameters
The response will be a json with all requested values updated. See response example for more information.
List log files
List log files
Request example:
curl -k -X GET -H "ZAPI_KEY: <ZAPI_KEY_STRING>"
https://<zevenet_server>:444/zapi/v3.1/zapi.cgi/system/logs
GET /system/logs
List the available log files.
Response example:
{
"description" : "Get logs",
"params" : [
{
"date" : "Mon Jan 30 06:25:02 2017",
"file" : "syslog.4.gz"
},
{
"date" : "Tue Jan 31 06:25:03 2017",
"file" : "syslog.3.gz"
},
{
"date" : "Wed Feb 1 06:25:04 2017",
"file" : "syslog.2.gz"
},
{
"date" : "Thu Feb 2 06:25:03 2017",
"file" : "syslog.1"
},
{
"date" : "Sun Jan 29 06:25:03 2017",
"file" : "syslog.5.gz"
},
{
"date" : "Fri Feb 3 04:28:56 2017",
"file" : "syslog"
}
]
}
Response parameters
The response will be a JSON with an array of log file. The parameters of each object are:
| Field | Type | Description |
|---|---|---|
| date | String | The date of the last file modification. |
| file | String | File name of log files. It is used as log unique identifier. |
Show lines of a log files
Show lines of a log files
Request example:
curl -k -X GET -H "ZAPI_KEY: <ZAPI_KEY_STRING>"
https://<zevenet_server>:444/zapi/v3.1/zapi.cgi/system/logs/kern.log/lines/2
GET /system/logs/<file>/lines/<lines>
List a number of lines of a log file. The URI param file is the log file from reading. Lines is the number of lines to show from the final.
Response example:
{
"description" : "Show a log file",
"log" : [
"Aug 28 09:44:00 maq2 kernel: [258451.740173] Netfilter messages via NETLINK v0.30.\n",
"Aug 28 09:44:00 maq2 kernel: [258451.775666] ctnetlink v0.93: registering with nfnetlink.\n"
]
}
Response parameters
The response will be a JSON with an array of log file. The key is log and its value is a array with the number of lines requested.
Download a log file
Download a log files
Request example:
curl -k -X GET -H "ZAPI_KEY: <ZAPI_KEY_STRING>"
https://<zevenet_server>:444/zapi/v3.1/zapi.cgi/system/logs/syslog.2.gz > log.gz
GET /system/logs/<file>
Download a log file of the available log files listed while GET request.
file is the log file unique identifier.
System - Backups
With the Backup option you can save the current system configuration and download it.
In this section, you will be able to create, restore, upload and download backup files.
List backups
List backups
Request example:
curl -k -X GET -H "ZAPI_KEY: <ZAPI_KEY_STRING>"
https://<zevenet_server>:444/zapi/v3.1/zapi.cgi/system/backup
GET /system/backup
Response example:
{
"description" : "Get backups",
"params" : [
{
"date" : "Fri Feb 3 06:01:04 2017",
"name" : "newbackup"
},
{
"date" : "Fri Feb 3 05:50:48 2017",
"name" : "firstConf"
}
]
}
Response parameters
The response will be a JSON with an array of backups. The parameters of each array element are:
| Field | Type | Description |
|---|---|---|
| date | String | The date of the last modification. |
| name | String | It is the file name used as unique identifier. The file extension is .tar.gz. |
Create a backup
Create a backup
Request example:
curl -k -X POST -H 'Content-Type: application/json' -H "ZAPI_KEY: <ZAPI_KEY_STRING>"
-d '{"name":"firstConf"}'
https://<zevenet_server>:444/zapi/v3.1/zapi.cgi/system/backup
POST /system/backup
Create a system configuration backup of the current configuration.
Request parameters
| Field | Type | Description |
|---|---|---|
| name | String | It is the file name used as unique identifier. The file extension is .tar.gz. |
Response example:
{
"description" : "Create a backups",
"message" : "Backup firstConf was created successful.",
"params" : "firstConf"
}
Download a backup
Download a backup
Request example:
curl -k -X GET -H "ZAPI_KEY: <ZAPI_KEY_STRING>"
https://<zevenet_server>:444/zapi/v3.1/zapi.cgi/system/backup/firstConf > ~/zevenetConf.tar.gz
The backup file is in TAR GZ format.
GET /system/backup/<name>
Download a system configuration backup. name is the backup unique identifier.
Upload a backup
Upload a backup
Request example:
curl -k -X PUT -H 'Content-Type: text/plain'
--data-binary @/opt/1mar.tar.gz -H "ZAPI_KEY: <ZAPI_KEY_STRING>"
https://<zevenet_server>:444/zapi/v3.1/zapi.cgi/system/backup/newbackup
PUT /system/backup/<name>
Upload a local stored backup to Zevenet. name is the backup unique identifier which will be stored in Zevenet.
Request parameters
It is necessary to use –data-binary to upload a backup.
Response example:
{
"description" : "Upload a backup",
"message" : "Backup newbackup was created successful.",
"params" : "newbackup"
}
Delete a backup
Delete a backup
Request example:
curl -k -X DELETE -H "ZAPI_KEY: <ZAPI_KEY_STRING>"
https://<zevenet_server>:444/zapi/v3.1/zapi.cgi/system/backup/firstConf
DELETE /system/backup/<name>
Delete a backup file from Zevenet system. name is the backup unique identifier.
Response example:
{
"description" : "Delete backup firstConf'",
"message" : "The list firstConf has been deleted successful.",
"success" : "true"
}
Apply a backup
Apply a backup
Request example:
curl -k -X POST -H 'Content-Type: application/json' -H "ZAPI_KEY: <ZAPI_KEY_STRING>"
-d '{"action":"apply"}'
https://<zevenet_server>:444/zapi/v3.1/zapi.cgi/system/backup/firstConf/actions
POST /system/backup/<name>/actions
Restore the configuration from a backup file. name is the backup unique identifier.
Request parameters
| Field | Type | Description |
|---|---|---|
| action | String | To restore the backup configuration, the value must be apply. |
Response example:
{
"description" : "Apply a backup to the system",
"params" : {
"action" : "apply"
}
}
System - Notifications
Notifications are formed by two elements: Sender method and type of alert.
In alert section you will be able to choose which type of alert you wish receive. Actually, the alerts are focus in backend or cluster status, so the balancer will send a notification if some switchs.
In method section you will be able to choose which sender will be used when Zevenet has to send a notification.
Show alert status
Show alert status
Request example:
curl -k -X GET -H "ZAPI_KEY: <ZAPI_KEY_STRING>"
https://<zevenet_server>:444/zapi/v3.1/zapi.cgi/system/notifications/alerts
GET /system/notifications/alerts
List all type of alerts with their status.
Response example:
{
"description" : "Get notifications alert status",
"params" : [
{
"alert" : "backends",
"status" : "disabled"
},
{
"alert" : "cluster",
"status" : "disabled"
}
]
}
Response parameters
| Field | Type | Description |
|---|---|---|
| alert | String | Type of alert, it is used as alert unique identifier. The available alerts are: backend, notify when a backend changes of status; or cluster, send a notification when the cluster master node switchs to other node. |
| status | String | Show if alert is disabled, the system doesn’t send notification when there are an event; or enabled, the system sends a alert when it is detected a changed of status. |
Retrieve notification alerts
Retrieve notification alerts
Request example:
curl -k -X GET -H "ZAPI_KEY: <ZAPI_KEY_STRING>"
https://<zevenet_server>:444/zapi/v3.1/zapi.cgi/system/notifications/alerts/backends
GET /system/notifications/alerts/<alert>
Show the configuration about a type of alert.
alert is the alert unique identifier.
Response example:
{
"description" : "Get notifications alert backends settings",
"params" : {
"avoidflappingtime" : 5,
"prefix" : "",
"status" : "disabled"
}
}
Response parameters
| Field | Type | Description |
|---|---|---|
| avoidflappingtime | Number | Sometimes backends are available or not in a short period of time, this field allow to configure a period of time to avoid notifications message while backend is changing status, once this period of time concludes, if the backend status it it different to start, then the notification is sent. |
| prefix | String | It is a prefix for the email subject, that are sent by the system for this kind of alert. |
| status | String | Show if alert is disabled, the system doesn’t send notification when there are an event; or enabled, the system sends a alert when it is detected a changed of status. |
Modify notification alert
Modify notification alerts
Request example:
curl -k -X POST -H 'Content-Type: application/json' -H "ZAPI_KEY: <ZAPI_KEY_STRING>"
{"avoidflappingtime":10,"prefix":"[backend alert]"}
https://<zevenet_server>:444/zapi/v3.1/zapi.cgi/system/notifications/alerts/backends
POST /system/notifications/alerts/<alert>
alert is the alert unique identifier.
Request parameters
| Field | Type | Description |
|---|---|---|
| avoidflappingtime | Number | Sometimes backends are available or not in a short period of time, this field allow to configure a period of time to avoid notifications message while backend is changing status, once this period of time concludes, if the backend status it it different to start, then the notification is sent. This parameter is not in cluster alerts, cluster has it own swich time. |
| prefix | String | It is a prefix for the email subject, that are sent by the system for this kind of alert. |
Response example:
{
"description" : "Set notifications alert backends",
"params" : {
"avoidflappingtime" : 10,
"prefix" : "[backend alert]"
}
}
Response parameters
The response will be a json with all requested values updated. See response example for more information.
Enable alerts
Enable alerts
Request example:
curl -k -X POST -H 'Content-Type: application/json' -H "ZAPI_KEY: <ZAPI_KEY_STRING>"
{"action":"enable"}
https://<zevenet_server>:444/zapi/v3.1/zapi.cgi/system/notifications/alerts/backends/actions
POST /system/notifications/alerts/<alert>/actions
Enable or disable the notifications for a type of alert.
alert is the alert unique identifier.
Request parameters
| Field | Type | Description |
|---|---|---|
| action | String | The actions available for alerts are disabld, the system doesn’t send notification when there are an event; or enable, the system sends a alert when it is detected a changed of status. |
Response example:
{
"description" : "Set notifications alert backends actions",
"params" : {
"action" : "enable"
}
}
Response parameters
The response will be a json with all requested values updated. See response example for more information.
Retrieve email configuration
Retrieve email configuration
Request example:
curl -k -X GET -H "ZAPI_KEY: <ZAPI_KEY_STRING>"
https://<zevenet_server>:444/zapi/v3.1/zapi.cgi/system/notifications/methods/email
GET /system/notifications/methods/email
Show all configuration of email sender.
Note: SMTP port used for sending emails is TCP 25 even if TLS is enabled.
Response example:
{
"description" : "Get notifications email methods",
"params" : {
"from" : "user@zevenet.com",
"method" : "email",
"password" : "******",
"server" : "smtp.gmail.com",
"tls" : "true",
"to" : "adminuser@zevenet.net",
"user" : "user@zevenet.com"
}
}
Response parameters
| Field | Type | Description |
|---|---|---|
| from | String | Email account that sends the email, this account will appear in the SMTP header From: and it will be used if the reciever replies the email. |
| method | String | It is the method unique identifier. Actually the available method is email. |
| password | String | Password for user SMTP account, this password is needed if Server requires SMTP authentication. |
| server | String | SMTP server through the email is sent. |
| tls | String | Enable TLS validation for sending email, this property uses STARTTLS and this feature has to be supported in the SMTP server. Some SMTP servers require enable it. The possible values are: true, TLS validation is enabled for sending email; or false, sending email doesn’t use TLS validation. |
| to | String | Email account that receives the email, this account will appear in the SMTP header To. |
| user | String | Email account allowed to send emails, this account is needed if server requires SMTP authentication. |
Modify email configuration
Modify email configuration
Request example:
curl -k -X POST -H 'Content-Type: application/json' -H "ZAPI_KEY: <ZAPI_KEY_STRING>"
-d '{"from":"user@zevenet.com","password":"verystrongpass","server":"smtp.gmail.com","to":"adminuser@zevenet.net","tls":"true","user":"user@zevenet.com"}'
https://<zevenet_server>:444/zapi/v3.1/zapi.cgi/system/notifications/methods/email
POST /system/notifications/methods/email
Modify the configuration of email sender method.
Request parameters
| Field | Type | Description |
|---|---|---|
| from | String | Email account that sends the email, this account will appear in the SMTP header From: and it will be used if the reciever replies the email. |
| password | String | Password for user SMTP account, this password is needed if Server requires SMTP authentication. |
| server | String | SMTP server through the email is sent. |
| tls | String | Enable TLS validation for sending email, this property uses STARTTLS and this feature has to be supported in the SMTP server. Some SMTP servers require enable it. The possible values are: true, TLS validation is enabled for sending email; or false, sending email doesn’t use TLS validation. |
| to | String | Email account that receives the email, this account will appear in the SMTP header To. |
| user | String | Email account allowed to send emails, this account is needed if server requires SMTP authentication. |
Response example:
{
"description" : "Get notifications email methods",
"params" : {
"from" : "user@zevenet.com",
"method" : "email",
"password" : "verystrongpass",
"server" : "smtp.gmail.com",
"tls" : "true",
"to" : "adminuser@zevenet.net",
"user" : "user@zevenet.com"
}
}
Response parameters
The response will be a json with all requested values updated. See response example for more information.
Send a test mail
Send a test mail
Request example:
curl -k -X POST -H 'Content-Type: application/json' -H "ZAPI_KEY: <ZAPI_KEY_STRING>"
-d '{"action":"test"}'
https://<zevenet_server>:444/zapi/v3.1/zapi.cgi/system/notifications/methods/email/actions
POST /system/notifications/methods/email/actions
Send a test mail with the email configuration, to test it.
Request parameters
| Field | Type | Description |
|---|---|---|
| action | String | The value to send a test mail is test. |
Response example:
{
"description" : "Send test mail",
"message" : "Test mail sent successful.",
"success" : "true"
}
Download a supportsave
Download a supportsave
Request example:
curl -k -X GET -H "ZAPI_KEY: <ZAPI_KEY_STRING>"
https://<zevenet_server>:444/zapi/v3.1/zapi.cgi/system/supportsave > supportsave.tar.gz
GET /system/supportsave
Get system status image with all configuration and process running in the system. This supportsave it is necessary to find issues or support assistance.
System - Cluster
The cluster is the element done by a master node, that it manages the connections fordward the backends, and a backup node checking the master, it is prepared to swich to master node if it goes to down status.
When there is a status switched, the backup node will restore all connection status in itself. So, client does not detected an interruption in the service.
This let put the load balancer in high availability. So if there are any issue in a Zevenet, the service will continue working with the uploaded configuration.
Show the cluster configuration
Show the cluster configuration
Request example:
curl -k -X GET -H "ZAPI_KEY: <ZAPI_KEY_STRING>"
https://<zevenet_server>:444/zapi/v3.1/zapi.cgi/system/cluster
GET /system/cluster
Show all configuration about the cluster.
Response BODY:
{
"description" : "Show the cluster configuration",
"params" : {
"check_interval" : 5,
"failback" : "disabled",
"interface" : "eth0",
"nodes" : [
{
"ip" : "192.168.100.241",
"name" : "canoDEV4100",
"node" : "local"
},
{
"ip" : "192.168.100.240",
"name" : "maqvir",
"node" : "remote"
}
]
}
}
Response parameters
The response will be a JSON object with the cluster configuration and an array with the nodes in it.
Cluster Object:
| Field | Type | Description |
|---|---|---|
| check_interval | Number | It is the waiting time between two checks of master node status. |
| failback | String | Which node has preference to be master. The values can be a name node, to give preference to a node; or disabled, if any node can be master and are no priority for one. |
| interface | String | Interface where the IP of node is configurated. |
| nodes | Object[] | Cluster’s nodes. |
Node Object:
| Field | Type | Description |
|---|---|---|
| ip | String | It is the IP configurated in the node to check the status of the node and to do the information replication. |
| name | String | It is the node hostname, and it is used as node unique identifier. |
| node | String | The possible values are: local, if node is which is receiving the zapi request; or remote, if is the other node configurated in cluster. |
Enable a cluster
Enable a cluster
Request example:
curl -k -X POST -H 'Content-Type: application/json' -H "ZAPI_KEY: <ZAPI_KEY_STRING>"
-d '{"local_ip":"192.168.100.241","remote_ip":"192.168.100.240","remote_password":"admin"}'
https://<zevenet_server>:444/zapi/v3.1/zapi.cgi/system/cluster
POST /system/cluster
Do a cluster communicating two balancers.
Request parameters
| Field | Type | Description | Required |
|---|---|---|---|
| remote_ip | String | IP of remote host used to the cluster. | true |
| local_ip | String | IP of local host used to the cluster. | true |
| remote_password | String | Root user password for remote balancer. | true |
Response BODY:
{
"description" : "Enabling cluster",
"message" : "Cluster enabled successfully",
"success" : "true"
}
Modify cluster configuration
Modify cluster configuration
Request example:
curl -k -X PUT -H 'Content-Type: application/json' -H "ZAPI_KEY: <ZAPI_KEY_STRING>"
-d '{"check_interval":4,"failback":"disabled"}'
https://<zevenet_server>:444/zapi/v3.1/zapi.cgi/system/cluster
PUT /system/cluster
Configure working mode parameters for cluster.
Request parameters
| Field | Type | Description |
|---|---|---|
| check_interval | Number | It is the waiting time between two checks of master node status. |
| failback | String | Which node has preference to be master. The values can be a name node, to give preference to a node; or disabled, if any node can be master and are no priority for one. |
Response BODY:
{
"description" : "Modifying the cluster configuration",
"params" : {
"check_interval" : "4",
"failback" : "disabled"
}
}
Disable the cluster
Disable the cluster
Request example:
curl -k -X DELETE -H 'Content-Type: application/json'
https://<zevenet_server>:444/zapi/v3.1/zapi.cgi/system/cluster
DELETE /system/cluster
Remove the cluster.
Response BODY:
{
"description" : "Disabling cluster",
"message" : "Cluster disabled successfully",
"success" : "true"
}
Maintenance mode
Maintenance mode
Request example:
curl -k -X POST -H 'Content-Type: application/json' -H "ZAPI_KEY: <ZAPI_KEY_STRING>"
-d '{"action":"maintenance","status":"enable"}'
https://<zevenet_server>:444/zapi/v3.1/zapi.cgi/system/cluster/actions
POST /system/cluster/actions
Change the local cluster node to maintenance mode.
Response BODY:
{
"description" : "Setting maintenance mode",
"message" : "Local cluster node changed to maintenance mode successfully",
"success" : "true"
}
Request parameters
| Field | Type | Description | Required |
|---|---|---|---|
| action | String | Action to apply to the cluster. The available action is maintenance. | true |
| status | String | Status to put the node, the possible values are enable, put it in maintenance mode; or disable, put the node available. | true |
Show nodes status
Show nodes status
Request example:
curl -k -X GET -H "ZAPI_KEY: <ZAPI_KEY_STRING>"
https://<zevenet_server>:444/zapi/v3.1/zapi.cgi/system/cluster/nodes
GET /system/cluster/nodes
Show the status of all nodes.
Response BODY:
{
"description" : "Cluster nodes status",
"params" : [
{
"ip" : "192.168.100.241",
"message" : "Node online and active",
"name" : "canoDEV4100",
"node" : "local",
"role" : "master",
"status" : "ok"
},
{
"ip" : "192.168.100.240",
"message" : "Node online and passive",
"name" : "maqvir",
"node" : "remote",
"role" : "backup",
"status" : "ok"
}
]
}
Response parameters
The response will be a JSON with key param and value an array of node status object.
Node status object
| Field | Type | Description |
|---|---|---|
| ip | String | It is the IP configurated in the node to check the status of the node and to do the information replication. |
| name | String | It is the node hostname, and it is used as node unique identifier. |
| node | String | The possible values are: local, if node is which is receiving the zapi request; or remote, if is the other node configurated in cluster. |
| message | String | Descriptive message that indicates the status and working mode of the node. |
| role | String | Actual working mode of this node. The possible values are: master, this node is managing the connections among backends and clients; or backup, this node has replied master status connections and master configuration, and it is checking that master service works. |
| status | String | Indicate if some cluster process is failing. |
Show localhost cluster status
Show localhost cluster status
Request example:
curl -k -X GET -H "ZAPI_KEY: <ZAPI_KEY_STRING>"
https://<zevenet_server>:444/zapi/v3.1/zapi.cgi/system/cluster/nodes/localhost
GET /system/cluster/nodes/localhost
Show the status of local node.
Response BODY:
{
"description" : "Cluster status for localhost",
"params" : {
"message" : "Node online and active",
"name" : "canoDEV4100",
"role" : "master",
"status" : "ok"
}
}
Response parameters
| Field | Type | Description |
|---|---|---|
| message | String | Descriptive message that indicates the status and working mode of the node. |
| name | String | It is the node hostname, and it is used as node unique identifier. |
| role | String | Actual working mode of this node. The possible values are: master, this node is managing the connections among backends and clients; or backup, this node has replied master status connections and master configuration, and it is checking that master service works. |
| status | String | Indicate if some cluster process is failing. |