NAV Navbar
Logo
shell

Zevenet API v4.0 Reference

ZAPI (Zevenet Application Programming Interface) is the tool for system administrators to control the Zevenet load balancer behavior.

It is necessary active the root zapi user from the web interface before using it, System > Users.

Once the ZAPI user has been created, it is possible to send requests to the HTTP server. A URI request looks like:

HTTP verb https://zevenet_server:444/zapi/v4.0/zapi.cgi/URI_path,

where zevenet_server is the IP where HTTP service is listening, the HTTP manage interface, and the URI_path defines the object which will be requested. How to access and how to modify each Zevenet object will be defined within each documentation section.

The HTTP verbs accepted for the ZAPI are:

ZAPI parameters

ZAPI parameters

Request example:

curl -k -X POST -H "ZAPI_KEY: <ZAPI_KEY_STRING>"
-H 'Content-Type: application/json' -d ''
https://<zevenet_server>:444/zapi/v4.0/zapi.cgi/farms

A PUT and POST requests always need almost a parameter although the ZAPI call does not need any required (mandatory) parameter. If a PUT or POST request is sent without parameters, the ZAPI will return the list of expected parameters and their possible options.

Response example:

{
   "description" : "No parameter has been sent. Please, try with:",
   "params" : [
      {
         "name" : "profile",
         "options" : [
            "required"
         ],
         "possible_values" : [
            "http",
            "gslb",
            "l4xnat",
            "datalink"
         ]
      },
      {
         "format" : "ip_addr",
         "name" : "vip",
         "options" : [
            "required"
         ]
      },
      {
         "description" : "expects a port",
         "name" : "vport",
         "options" : [
            "required"
         ]
      },
      {
         "description" : "The farm name is required to have alphabet letters, numbers or hypens (-) only.",
         "format" : "farm_name",
         "name" : "farmname",
         "options" : [
            "required"
         ]
      }
   ]
}

Response parameters

The response is a list of fields that describes the parameter and the possible options of configuration:

Parameter description:

Field Type Description
name String It is the key to the accepted value. The following parameters are used to define it.
description String It is information about the expected value.
interval String The parameter has to have a numeric value respecting the low, high or both limits. The values used as limits are taken as valid.
format String It can be a clue with the expected format of the parameter, it can be a regular expression or a key that identifies the data.
possible_values String[] It is the list of possible values that the parameter has to have.
options String[] It shows more configuration to take in mind.

List of options:

Field Description
required This option indicates that the parameter is mandatory, it has to be sent in the request.
non_blank This option allows sending an empty string as the parameter value. It could be useful to unset the parameter.

Error codes

The ZAPI can response one of the following error codes:

Error Code Brief Description
400 Bad Request Some request parameter is incorrect.
401 Unauthorized Your ZAPI key is wrong.
402 Certificate not valid The load balancer needs a valid certificate to process the request.
403 Forbidden The user owner of the ZAPI key has not permissions for the request or the object used in it.
404 Not Found The URI used or one object used in the call does not exist.
405 Method Not Allowed The HTTP verb does not exist or is not implemented for the current ZAPI call.
406 Not Acceptable This feature is not temporality available.
409 Conflict The request is valid, but it could not be processed, the new configuration created a conflict with the current one. Syslog could offer more information.
410 Gone This feature has been removed.
500 Internal Server Error An error occurred in the server.
504 Gateway Timeout The server response timeout has been reached and the request has not been finished its processing.

Changes log

This is the list of changes that have been included in each version. The list of changes list in a ZAPI version is always regarding the before then.

API 4.0

List a summary of the farms and services grouped for module:

Added: /farms/modules/summary

Actions to link WAF rule set with HTTP farms:

Added: GET|POST|PUT|DELETE /farms/<farmname>/ipds/waf/*

Modified: GET /farms/<farm>

Move certificates in a HTTPS farms:

Added: POST /farms/<farm>/certificates/<cert>/actions

Modify farms call related with l4xnat to support the new core:

Modified: GET|POST|PUT|DELETE /farms/<l4farm>

Added the DHCP and MAC features in the following ZAPI calls:

modified: PUT /interfaces/nic/<if>

modified: PUT /interfaces/bonding/<if>

modified: POST /interfaces/vlan

modified: PUT /interfaces/vlan/<if>

Rename parameter to copy a farm guardian:

Modified: POST /monitoring/fg

Management of the IPDS package:

Added: GET /ipds/package

Added: POST /ipds/package/actions

New web application firewall, WAF, feature:

Added: GET|POST|PUT|DELETE /ipds/waf/*

Remove the call for copying RBL rules. Now it is a parameter of the creating call:

removed: POST /ipds/rbl/<name>

modified: POST /ipds/waf/<name>

The features factory reset, proxy and check packages updates have been added:

Added: POST /system/factory

Added: GET /system/proxy

Added: POST /system/proxy

Added: GET /system/packages

Add parameter to manage the web GUI menus:

Added: GET /rbac/menus

Modified: PUT /rbac/roles/<ROLE>

Activation Certificates

The activation certificate is the license issued by Zevenet that enables the complete use of the load balancer in its Enterprise version.

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/v4.0/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.

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/v4.0/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 overwritten.

Response example:

{
   "description" : "Upload activation certificate",
   "message" : "Activation certificate uploaded",
   "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/v4.0/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"
}

SSL Certificates

Zevenet supports certificates in PEM format to use them with HTTP farms set up 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/v4.0/zapi.cgi/certificates

GET /certificates

List all CSR and PEM certificates in the certificates store, those certificates can be used with HTTPS farms.

Response example:

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 contains the key attributes below.

{
   "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[ ] Certificate objects list.

Certificate Object

Field Type Description
CN String Domain common name.
creation String Creation date.
expiration String Expiration date.
file String It is the 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/v4.0/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.

Response headers:

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.

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/v4.0/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 refer.

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:
...

Delete a Certificate

Delete a Certificate

Request example:

curl -k -X DELETE -H "ZAPI_KEY: <ZAPI_KEY_STRING>"
https://<zevenet_server>:444/zapi/v4.0/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"
}

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/v4.0/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 localized. true
mail 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/v4.0/zapi.cgi/certificates/example.pem

POST /certificates/<file>

Upload a PEM certificate for HTTP farms with HTTPS listener.

Request URI parameters

Requires the parameter --tcp-nodelay, and --data-binary to upload the file in binary mode.

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"
}

List Ciphers

List Ciphers

Request example:

curl -k -X GET -H "ZAPI_KEY: <ZAPI_KEY_STRING>"
https://<zevenet_server>:444/zapi/v4.0/zapi.cgi/ciphers

GET /ciphers

List the available ciphers that an HTTPS farm can use.

The SSL offloading cipher will be available only if it is supported by the processor.

Response example:

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 contains the key attributes below.

{
   "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 a unique identifier.
description String Friendly name.

Farms

Zevenet can 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 a specific action with the network traffic, it is important to understand what can do each farm profile to obtain the best results of Zevenet ADC.

List a summary of farms

List a summary farms

Request example:

curl -k -X GET -H "ZAPI_KEY: <ZAPI_KEY_STRING>"
https://<zevenet_server>:444/zapi/v4.0/zapi.cgi/farms/modules/summary

GET /farms/modules/summary

List a summary with the farms in the system, grouped by module.

Response example:

{
   "description" : "Farm Modules summary",
   "params" : {
      "dslb" : [],
      "gslb" : [
         {
            "name" : "dnsServ",
            "profile" : "gslb",
            "services" : []
         }
      ],
      "lslb" : [
         {
            "name" : "CatalogueWeb",
            "profile" : "http",
            "services" : [
               "technology",
               "food"
            ]
         },
         {
            "name" : "shopApp",
            "profile" : "http",
            "services" : [
               "provider",
               "clients"
            ]
         },
         {
            "name" : "VirtualApps",
            "profile" : "l4xnat"
         }
      ]
   }
}

Response parameters

The response will be a JSON object with a key set to params. The value of this will be an array of farms with their services.

Farm Object:

Field Type Description
farmname String Farm descriptive name. It is used as a unique identifier for farms.
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
service String[] It is the list of services name that the farm contains. This field will be available in farms of type http, https, and gslb.

List all farms

List all farms

Request example:

curl -k -X GET -H "ZAPI_KEY: <ZAPI_KEY_STRING>"
https://<zevenet_server>:444/zapi/v4.0/zapi.cgi/farms

GET /farms

List all available farms

Response example:

{
   "description" : "List farms",
   "params" : [
      {
         "farmname" : "httpFarm",
         "profile" : "http",
         "status" : "up",
         "vip" : "192.168.101.146",
         "vport" : "81"
      }
   ]
}

Response parameters

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 a unique identifier for farms.
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 the 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.

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/v4.0/zapi.cgi/farms/FarmHTTP

DELETE /farms/<farmname>

Delete a farm through its farm name identifier.

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/v4.0/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 The action to execute, the possibilities are: stop, the farm will be stopped, cutting the current connections and does not accepting more connections; start, the farm will be started, running the listener and balancing the new connections between its backends; 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

The HTTP profile is an advanced layer 7 load balancing (or Application Delivery Controller) with proxy special properties. This profile offers some features like HTTPS load balancing combined with SSL offload acceleration. This profile is adequate 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. 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/v4.0/zapi.cgi/farms/httpFarm

GET /farms/<farmname>

Show all configuration about a given farm.

Response example:

{
   "description" : "List farm httpFarm",
   "ipds" : {
      "blacklists" : [
         {
            "name" : "outside",
            "status" : "down"
         }
      ],
      "dos" : [],
      "rbl" : [
         {
            "name" : "protection_ssh",
            "status" : "up"
         }
      ],
      "waf" : [
         {
            "name" : "XSSi",
            "status" : "down"
         },
         {
            "name" : "SQLi",
            "status" : "up"
         }
      ]
   },
   "params" : {
      "addheader" : [
         {
            "header" : "load-balancer: true",
            "id" : 0
         }
      ],
      "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.",
      "headremove" : [
         {
            "id" : 0,
            "pattern" : "^client"
         }
      ],
      "httpverb" : "MSRPCext",
      "ignore_100_continue" : "true",
      "listener" : "https",
      "logs" : "false",
      "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,
         "farmguardian" : "check_tcp",
         "httpsb" : "false",
         "id" : "service3",
         "leastresp" : "false",
         "redirect" : "http://192.168.101.254/index.html",
         "redirect_code" : 302,
         "redirecttype" : "default",
         "sessionid" : "",
         "sts_status" : "false",
         "sts_timeout" : 0,
         "ttl" : 0,
         "urlp" : "",
         "vhost" : ""
      },
      {
         "backends" : [
            {
               "alias" : "http-server",
               "id" : 0,
               "ip" : "192.168.0.168",
               "port" : 80,
               "status" : "up",
               "timeout" : null,
               "weight" : null
            }
         ],
         "cookiedomain" : "",
         "cookieinsert" : "false",
         "cookiename" : "",
         "cookiepath" : "",
         "cookiettl" : 0,
         "farmguardian" : null,
         "httpsb" : "false",
         "id" : "srv",
         "leastresp" : "false",
         "persistence" : "",
         "redirect" : "",
         "redirecttype" : "",
         "sessionid" : "",
         "sts_status" : "false",
         "sts_timeout" : 0,
         "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 Object[] Blacklist rules applied to the farm.
dos Object[] DoS rules applied to the farm.
rbl Object[] RBL rules applied to the farm.
waf Object[] It is an object with one key, name.

Blacklist, DoS and RBL Object:

Field Type Description
name String The rule name.
status String Rule status.

Parameters object for HTTP farms:

Field Type Description
addheader Object[] It is a list of objects with the headers to add to the backend.
certlist Object[] Only if the listener is HTTPS. Certificates list is been used by the farm, they have in PEM format, it is allowed to add more than one PEM certificate to the same farm for SNI support. 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 attribute is used only when ciphers field has the value “customsecurity”.
ciphers String Only if the listener is HTTPS. Used to build a list of ciphers accepted by SSL connections 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 an 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 an 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 responding with the 414 HTTP error code.
error500 String Personalized message for responding with the 500 HTTP error code.
error501 String Personalized message for responding with the 501 HTTP error code.
error503 String Personalized message for responding with the 503 HTTP error code.
headremove Object[] It is a list of regular expressions to remove headers from the client requests. The removed headers will not reach the backend.
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-sensitive.
ignore_100_continue String If this field has the value true the 100 continue HTTP header will be ignored; if the value is false, the 100 continue header will be processed.
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.
logs String The farm Logs the trace of the HTTP connections. If this parameter has the value true, the logs are enabled; if it has the value false, logs are disabled.
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, activated disabled, inactivated 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 the 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, no 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.
farmguardian String It is the FarmGuardian name that is checking the backend status. FarmGuardian will be running while the farm is in up status.
httpsb String This parameter indicates to the farm that the backends are set to use 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 response balancing method. true frequently the profile checks which backend is taking less time to respond to send more connections to this one, the 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 like a special backend, as the client request is answered by a redirect to a new URL automatically. If the redirect is configured then the request will not be forwarded to the backend, a Redirect will be responded to the client instead.
redirect_code Number It is the HTTP code returned when a redirect is configurated. The possible values are 301, 302, 307,
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 available 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.
sts_status String Status of the Strict Transport Security header. To enable this feature, it is necessary to set the farm listener as HTTPS. The possible values are: true to enable STS directive in the service; or false to disable STS directive in the service.
sts_timeout Number Time (in seconds) that the client remember that the service only is available with HTTS.
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 determining 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 an HTTP farm. PCRE regular expression is supported.

Backend object for HTTP farms:

Field Type Description
alias String It is a nick to help to identify the backend. Alias
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 maintenance tasks; undefined, the backend status has been not checked.
timeout Number It’s the maximum time waiting for the backend response before than marking it as unavailable. This time is in seconds.
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. The possible values are from 1 to 9.

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/v4.0/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 a 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. The 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 the 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", "logs":"true",
"cipherc":"TLSv1+SSLv3+HIGH:-MEDIUM:-LOW*:-ADH*"}' https://<zevenet_server>:444/zapi/v4.0/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 it 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 an 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 an 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 activated; disabled inactivated; 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-sensitive.
ignore_100_continue String If this field has the value true the 100 continue HTTP header will be ignored; if the value is false, the 100 continue header will be processed.
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.
logs String The farm Logs the trace of the HTTP connections. If this parameter has the value true, the logs are enabled; if it has the value false, logs are disabled.
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 attribute is used only when ciphers field has the value “customsecurity”.
newfarmname String The new Farm’s name. The 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",
      "logs" : "true",
      "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 the response example for more information.

Add an addheader directive

Add an addheader directive

Request example:

curl -k -X POST -H 'Content-Type: application/json' -H "ZAPI_KEY: <ZAPI_KEY_STRING>"
-d '{"header":"loadbalancer: true"}' https://<zevenet_server>:444/zapi/v4.0/zapi.cgi/farms/MyHttpFarm/addheader

POST /farms/<farmname>/addheader

The farm will add the header to the backend.

Request parameters

Field Type Description Required
header String It is a string with the header that will be sent to the backend. true

Response example:

{
   "description" : "Add addheader directive.",
   "message" : "Added a new item to the addheader list",
   "status" : "needed restart",
   "success" : "true"
}

Delete an addheader directive

Delete an addheader directive

Request example:

curl -k -X DELETE -H "ZAPI_KEY: <ZAPI_KEY_STRING>"
https://<zevenet_server>:444/zapi/v4.0/zapi.cgi/farms/MyHttpFarm/addheader/0

DELETE /farms/<farmname>/addheader/<index>

index is the index of the addheader array to delete.

Response example:

{
   "description" : "Delete addheader directive.",
   "message" : "The addheader 0 was deleted successfully",
   "status" : "needed restart",
   "success" : "true"
}

Add a headremove directive

Add a headremove directive

Request example:

curl -k -X POST -H 'Content-Type: application/json' -H "ZAPI_KEY: <ZAPI_KEY_STRING>"
-d '{"pattern":"^client:"}' https://<zevenet_server>:444/zapi/v4.0/zapi.cgi/farms/MyHttpFarm/headremove

POST /farms/<farmname>/headremove

Remove certain headers from the incoming requests. All occurrences of the matching specified header will be removed.

Request parameters

Field Type Description Required
pattern String It is a string with a regexp to look for in the client requests. If some header matches in the pattern, the header will be removed true

Response example:

{
   "description" : "Add headremove directive.",
   "message" : "Added a new item to the headremove list",
   "status" : "needed restart",
   "success" : "true"
}

Delete a headremove directive

Delete a headremove directive

Request example:

curl -k -X DELETE -H "ZAPI_KEY: <ZAPI_KEY_STRING>"
https://<zevenet_server>:444/zapi/v4.0/zapi.cgi/farms/MyHttpFarm/headremove/0

DELETE /farms/<farmname>/headremove/<index>

index is the index of the headremove array to delete.

Response example:

{
   "description" : "Delete headremove directive.",
   "message" : "The headremove 0 was deleted successfully",
   "status" : "needed restart",
   "success" : "true"
}

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/v4.0/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"
}

Move a Certificate

Move a Certificate

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/v4.0/zapi.cgi/farms/newfarm/certificates/certif.pem/actions

POST /farms/<farmname>/certificates/<file>/actions

The URI file parameter is the certificate file name that is going to be moved.

This feature allows moving the certificates to alter the order that they will be checked.

Request parameters

Field Type Description Required
position Integer It is the position that the certificate will have in the farm configuration when the ZAPI call will be processed true

Response example:

{
    "description" : "Move service",
    "params" : {
        "position" : 0
    },
    "status" : "needed restart",
    "info" : "There\'re changes that need to be applied, stop and start farm to apply them!",
    "message" : "certif.pem was moved successfully."
}

Delete a Certificate

Delete a Certificate

Request example:

curl -k -X DELETE -H "ZAPI_KEY: <ZAPI_KEY_STRING>"
https://<zevenet_server>:444/zapi/v4.0/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 an HTTPS listener. The certificate will not be deleted from 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/v4.0/zapi.cgi/farms/httpFarm/ipds/blacklists

POST /farms/<farmname>/ipds/<dos|blacklists|rbl|waf>

Apply a blacklist, DoS, RBL or WAF rule to the farm.

Request parameters

Field Type Description
name String IPDS rule name used as a unique identifier.

Response example:

{
   "description" : "Apply a rule to a farm",
   "message" : "Blacklist rule china was applied successful to the farm httpFarm.",
   "success" : "true"
}

Move an IPDS rule

Move an IPDS rule

Request example:

curl -k -X POST -H 'Content-Type: application/json' -H "ZAPI_KEY: <ZAPI_KEY_STRING>"
-d '{"position":2}'
https://<zevenet_server>:444/zapi/v4.0/zapi.cgi/ipds/waf/test_waf_ori/rules/0/actions

POST /farms/<farmname>/ipds/<waf>/actions

The move IPDS rules are only available for WAF rules. In this kind of rules is important the order that is going to be checked.

The waf URI parameter is the ruleset name of the set is going to be moved.

Request parameters

Field Type Description Required
position Integer It is the position that the WAF rule set will have in the farm configuration when the ZAPI call will be processed true

Response example:

{
    "message" : "The rule was moved properly to the position 2.",
    "description" : "Move a rule in the set test_waf_ori"
}

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/v4.0/zapi.cgi/farms/httpFarm/ipds/blacklists/china

DELETE /farms/<farmname>/ipds/<dos|blacklists|rbl|waf>/<name>

Remove a blacklist, DoS, RBL or WAF rule from a given farm using its indicator 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 an 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 to match the correct service for every client request. This service definition will be used by the farm to determine the backends servers that could deliver the response to the client.

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/v4.0/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" : [
         {
            "alias" : "http-server",
            "id" : 0,
            "ip" : "192.168.100.254",
            "port" : 80,
            "status" : "up",
            "timeout" : 20,
            "weight" : null
         },
         {
            "alias" : "http-server",
            "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,
      "farmguardian" : "check_tcp-cut_conns",
      "httpsb" : "false",
      "id" : "serv",
      "leastresp" : "false",
      "persistence" : "COOKIE",
      "redirect" : "",
      "redirect_code" : "",
      "redirecttype" : "",
      "sessionid" : "JSESSIONID",
      "sts_status" : "false",
      "sts_timeout" : 0,
      "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 the 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.
farmguardian String It is the FarmGuardian name that is checking the backend status. FarmGuardian will be running while the farm is in up status.
httpsb String This parameter indicates to the farm that the backends are configured to use HTTPS, 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 response balancing method. true frequently the profile checks which backend is taking less time to respond 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 like a special backend, as the client request is answered by a redirect to a new URL automatically. If the redirect is configured then the request will not be forwarded to the backend, a Redirect will be responded to the client instead.
redirect_code Number It is the HTTP code returned when a redirect is configurated. The possible values are 301, 302, 307.
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 the default option. If the redirect field is not configurated, this field will be an empty string.
sessionid String It is available 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.
sts_status String Status of the Strict Transport Security header. To enable this feature, it is necessary to set the farm listener as HTTPS. The possible values are: true to enable STS directive in the service; or false to disable STS directive in the service.
sts_timeout Number Time (in seconds) that the client remembers that the service only is available with HTTS.
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 determining 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 an HTTP farm. PCRE regular expression is supported.

Backend object for HTTP farms:

Field Type Description
alias String It is a nick to help to identify the backend. Alias
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 maintenance tasks; undefined, the backend status has been not checked.
timeout Number It’s the maximum time waiting for the backend response before putting it as down. This time is in seconds.
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. The possible values are from 1 to 9.

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://<zevenet_server>:444/zapi/v4.0/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 a 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_code":302,
"redirect":"http://zenloadbalancer.com","ttl":125,"sessionid":"sid","sts_status":"true","sts_timeout":21600000,
"leastresp":"true","httpsb":"true"}' https://<zevenet_server>:444/zapi/v4.0/zapi.cgi/farms/FarmHTTP/services/sev2

PUT /farms/<farmname>/services/<id>

Modify the parameters of a service in an HTTP profile. id is the service unique identifier that 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 an HTTP profile farm. PCRE regular expression is supported.
urlp String Allows determining 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.
redirect_code Number It is the HTTP code returned when a redirect is configurated. The possible values are 301, 302, 307,
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 behavior will apply only if redirect is not 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 the 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 available 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.
sts_status String Status of the Strict Transport Security header. To enable this feature, it is necessary to set the farm listener as HTTPS. The possible values are: true to enable STS directive in the service; or false to disable STS directive in the service.
sts_timeout Number Time (in seconds) that the client remembers that the service only is available with HTTS.
leastresp String It enables the least response balancing method. true, frequently the profile checks which backend is taking less time to respond to send more connections to this one, false, the profile doesn’t check which backend is taking less time to respond.
httpsb String It indicates to the farm that the backends servers are set to use HTTPS, 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,
      "httpsb" : "true",
      "id" : "newsrv",
      "leastresp" : "true",
      "persistence" : "",
      "redirect" : "http://zenloadbalancer.com",
      "redirect_code" : 302,
      "redirecttype" : "default",
      "sessionid" : "sid",
      "sts_status" : "true",
      "sts_timeout" : 21600000,
      "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 needs to be taken to apply the changes.

Add FarmGuardian

Add FarmGuardian

Request example:

curl -k -X POST -H 'Content-Type: application/json' -H "ZAPI_KEY: <ZAPI_KEY_STRING>"
-d '{"name":"check_tcp-cut_conns"}' https://<zevenet_server>:444/zapi/v4.0/zapi.cgi/farms/FarmHTTP/services/service1/fg

POST /farms/<farmname>/services/<id>/fg

Apply a FarmGuardian to a service.

The URI parameter is the service unique identifier.

Request parameters

Field Type Description
name String FarmGuardian unique identifier. The FarmGuardians are created and modified in the monitoring section.

Response example:

{
   "description" : "Add the farm guardian check_tcp-cut_conns to the service service1 in the farm FarmHTTP",
   "message" : "Success, The farm guardian check_tcp-cut_conns was added to the service service1 in the farm FarmHTTP"
}

Remove FarmGuardian

Remove FarmGuardian

Request example:

curl -k -X DELETE -H "ZAPI_KEY: <ZAPI_KEY_STRING>"
https://<zevenet_server>:444/zapi/v4.0/zapi.cgi/farms/FarmHTTP/service/service1/fg/check_tcp-cut_conns

DELETE /farms/<farmname>/services/<id>/fg/<name>

Remove the FarmGuardian from a service in a farm.

Response example:

{
   "description" : "Remove the farm guardian check_tcp-cut_conns from the service service1 in the farm FarmHTTP",
   "message" : "Sucess, check_tcp-cut_conns was removed from the service service1 in the farm FarmHTTP"
}

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/v4.0/zapi.cgi/farms/FarmHTTP/services/service1/actions

POST /farms/<farmname>/services/<id>/actions

This action 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 is shown. this action restarts the farm automatically.

id is the service unique identifier that will be modified.

Request Parameters

Field Type Description Required
position Number Position where will be the service. The 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://<zevenet_server>:444/zapi/v4.0/zapi.cgi/farms/FarmHTTP/services/service1

DELETE /farms/<farmname>/services/<id>

Delete a given service of an HTTP profile. id is the service unique identifier that 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://<zevenet_server>:444/zapi/v4.0/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" : [
      {
         "alias" : null,
         "id" : 0,
         "ip" : "192.168.0.10",
         "port" : 88,
         "status" : "up",
         "timeout" : 12,
         "weight" : 1
      },
      {
         "alias" : null,
         "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
alias String It is a nick to help to identify the backend. Alias
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. The possible values are from 1 to 9.
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 maintenance 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://<zevenet_server>:444/zapi/v4.0/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 to a certain request.
weight Number It’s the weight value for the current backend. The possible values are from 1 to 9.

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 needs to be taken 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://<zevenet_server>:444/zapi/v4.0/zapi.cgi/farms/FarmHTTP/service/service1/backends/1

PUT /farms/<farmname>/services/<id>/backends/<id>

Modify the parameters of a backend HTTP service.

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. The possible values are from 1 to 9.

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 needs to be taken 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://<zevenet_server>:444/zapi/v4.0/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 an 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 effect 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://<zevenet_server>:444/zapi/v4.0/zapi.cgi/farms/newfarmHTTP/services/service1/backends/4

DELETE /farms/<farmname>/services/<id>/backends/<id>

Delete a given backend from an HTTP service.

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 creating load balancing farms that work in the layer 4 of the OSI model, with 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 the 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 another 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/v4.0/zapi.cgi/farms/l4farm

GET /farms/<farmname>

Show all configuration about a given farm.

Response BODY:

{
   "backends" : [
      {
         "alias" : null,
         "max_conns" : 0,
         "id" : 0,
         "ip" : "192.168.55.40",
         "port" : "88",
         "priority" : 2,
         "status" : "undefined",
         "weight" : 1
      },
      {
         "alias" : "server-1",
         "id" : 1,
         "max_conns" : 500,
         "ip" : "192.168.55.41",
         "port" : "88",
         "priority" : 3,
         "status" : "undefined",
         "weight" : 2
      }
   ],
   "description" : "List farm l4farm",
   "ipds" : {
      "blacklists" : [
            {
              "status" : "down",
              "name" : "blacklist"
            }
      ],
      "dos" : [
         {
             "name" : "newlimitconns",
             "status" : "down"
         }
      ],
      "rbl" : [
         {
            "name" : "protection_ssh",
            "status" : "up"
         }
      ]
   },
   "params" : {
      "algorithm" : "weight",
      "farmguardian" : "check_tcp-cut_conns",
      "listener" : "l4xnat",
      "logs" : "false",
      "nattype" : "nat",
      "persistence" : "ip",
      "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 Object[] Blacklist rules applied to the farm.
dos Object[] DoS rules applied to the farm.
rbl Object[] RBL rules applied to the farm.

Blacklist, DoS and RBL Object:

Field Type Description
name String The rule name.
status String Rule status.

Parameters object for L4xNAT farms:

Field Type Description
algorithm String Type of load balancing scheduling used to dispatch the traffic between the backends. The options are: leastconn forwards connection always to the least connection server; weight connection linear dispatching depending on the backend weight; roundrobin does a sequential select between the backend pool, each backend will receive the same number of requests; hash_srcip balances packets that match the same source IP to the same backend; hash_srcip_srcport balances packets that match the same source IP and port to the same backend; symhash balance packets that match the same source IP and port and destination IP and port, so it could hash a connection in both ways (during inbound and outbound).
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.
logs String The farm Logs packet information of the transport layer, it is not available application layer information. If this parameter has the value true, the logs are enabled; if it has the value false, logs are disabled.
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; In dsr (Direct Server Return) mode the client connects to the VIP, then the load balancer changes its destination MAC address for the backend MAC address (the server must be on the same link media as the load balancer); Stateless DNAT. In stateless_dnat the load balancer switch destination address for the backend address and forward it to the backend as DNAT does, but it doesn’t manage any kind of connection information.
persistence String This parameter forwards the incoming request to the same backend in base on the persistence mode chosen. The options are: “” empty value disables the persistence, each incoming packet will be balanced between the backends; ip or srcip, Source IP, will assign the same backend for every incoming connection depending on the source IP address only; Port, Source Port, will assign the same backend for every incoming connection depending on the source port only. srcmac, Source MAC, With this option, the farm will assign the same backend for every incoming connection depending on link-layer MAC address of the packet; srcip_srcport, Source IP and Source Port, will assign the same backend for every incoming connection depending on both, source IP and source port; srcip_dstport, Source IP and Destination Port, will assign the same backend for every incoming connection depending on both, source IP and destination port.
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, also for TCP, it is possible to set once of the following protocols in order to parse its headers and use it to distribute properly: ftp, irc, pptp, or sane; udp the load balancer only will balance UDP L4 protocol, also for UDP, it is possible to set once of the following protocols in order to parse its headers and use it to distribute properly: sip, tftp, amanda, netbios-ns, or snmp; sctp, the load balancer only will balance SCTP L4 protocol. If h323 is selected, the farm will listen the TCP and UDP requests and parse its headers to balance between the backends.
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. A unique port can be specified, a range port can be specified with separator : and several ports can be specified with separator ,.
farmguardian String It is the FarmGuardian name that is checking the backend status. FarmGuardian will be running while the farm is in up status.

Backend object for L4xNAT farms:

Field Type Description
alias String It is a nick to help to identify the backend. Alias
id Number ID to identify the backend in the farm backends pool.
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 the 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 maintenance 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 priority available where 1 is the most priority and 9 is the least priority. The farm will balance the requests using the weight parameter between the backends with more priority.
weight Number It’s the weight value for the current real server. Backends with more weight will receive more connections. The possible values are from 1 to 9.
max_conns Number It is the maximum number of connection that the backend is going to receive simultaneously. If it is set with a 0 value the backend has not defined any limit.

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/v4.0/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 the 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","logs":"true"}'
https://<zevenet_server>:444/zapi/v4.0/zapi.cgi/farms/newfarml4

PUT /farms/<farmname>

Modify the configuration of an L4xNAT farm.

Request parameters

Field Type Description
newfarmname String The new Farm’s name. The farm must be stopped.
logs String The farm Logs packet information of the transport layer, it is not available application layer information. If this parameter has the value true, the logs are enabled; if it has the value false, logs are disabled.
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. A unique port can be specified, a range port can be specified with separator : and several ports can be specified with separator ,.
persistence String This parameter forwards the incoming request to the same backend in base on the persistence mode chosen. The options are: “” empty value disables the persistence, each incoming packet will be balanced between the backends; ip or srcip, Source IP, will assign the same backend for every incoming connection depending on the source IP address only; Port, Source Port, will assign the same backend for every incoming connection depending on the source port only. srcmac, Source MAC, With this option, the farm will assign the same backend for every incoming connection depending on link-layer MAC address of the packet; srcip_srcport, Source IP and Source Port, will assign the same backend for every incoming connection depending on both, source IP and source port; srcip_dstport, Source IP and Destination Port, will assign the same backend for every incoming connection depending on both, source IP and destination port.
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; In dsr (Direct Server Return) mode the client connects to the VIP, then the load balancer changes its destination MAC address for the backend MAC address (the server must be on the same link media as the load balancer); Stateless DNAT. In stateless_dnat the load balancer switch destination address for the backend address and forward it to the backend as DNAT does, but it doesn’t manage any kind of connection information.
algorithm String Type of load balancing scheduling used to dispatch the traffic between the backends. The options are: leastconn forwards connection always to the least connection server; weight connection linear dispatching depending on the backend weight; roundrobin does a sequential select between the backend pool, each backend will receive the same number of requests; hash_srcip balances packets that match the same source IP to the same backend; hash_srcip_srcport balances packets that match the same source IP and port to the same backend; symhash balance packets that match the same source IP and port and destination IP and port, so it could hash a connection in both ways (during inbound and outbound).
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, also for TCP, it is possible to set once of the following protocols in order to parse its headers and use it to distribute properly: ftp, irc, pptp, or sane; udp the load balancer only will balance UDP L4 protocol, also for UDP, it is possible to set once of the following protocols in order to parse its headers and use it to distribute properly: sip, tftp, amanda, netbios-ns, or snmp; sctp, the load balancer only will balance SCTP L4 protocol. If h323 is selected, the farm will listen the TCP and UDP requests and parse its headers to balance between the backends.

Response example:

{
   "description" : "Modify farm l4farm",
   "params" : {
      "algorithm" : "weight",
      "logs" : "true",
      "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 the response example for more information.

Add FarmGuardian

Add FarmGuardian

Request example:

curl -k -X POST -H 'Content-Type: application/json' -H "ZAPI_KEY: <ZAPI_KEY_STRING>"
-d '{"name":"check_tcp-cut_conns"}' https://<zevenet_server>:444/zapi/v4.0/zapi.cgi/farms/l4Farm/fg

POST /farms/<farmname>/fg

Apply a FarmGuardian to the farm.

Request parameters

Field Type Description
name String FarmGuardian unique identifier. The FarmGuardians are created and modified in the monitoring section.

Response example:

{
   "description" : "Add the farm guardian check_tcp-cut_conns to the farm fgl4",
   "message" : "Success, The farm guardian check_tcp-cut_conns was added to the farm fgl4"
}

Remove FarmGuardian

Remove FarmGuardian

Request example:

curl -k -X DELETE -H "ZAPI_KEY: <ZAPI_KEY_STRING>"
https://<zevenet_server>:444/zapi/v4.0/zapi.cgi/farms/l4Farm/fg/check_tcp-cut_conns

DELETE /farms/<farmname>/fg/<name>

Remove the FarmGuardian from the farm.

Response example:

{
   "description" : "Remove the farm guardian check_tcp-cut_conns from the farm fgl4",
   "message" : "Sucess, check_tcp-cut_conns was removed from the farm fgl4"
}

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/v4.0/zapi.cgi/farms/l4Farm/ipds/blacklists

POST /farms/<farmname>/ipds/<dos|blacklists|rbl>

Apply blacklists, DoS or RBL rules to a farm.

Request parameters

Field Type Description
name String IPDS rule name used as a 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/v4.0/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 indicator 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://<zevenet_server>:444/zapi/v4.0/zapi.cgi/farms/l4farm/backends

GET /farms/<farmname>/backends

Get the list of backends in a service.

Response example:

{
   "description" : "List backends",
   "params" : [
      {
         "alias" : null,
         "id" : 0,
         "ip" : "192.5.1.1",
         "max_conns" : 400,
         "port" : 787,
         "priority" : 1,
         "status" : "up",
         "weight" : 1
      },
      {
         "alias" : "server-2",
         "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
alias String It is a nick to help to identify the backend. Alias
id Number ID to identify the backend in the farm backends pool.
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 the 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 maintenance tasks; undefined, the backend status has been not checked.
max_conns Number It’s the maximum number of concurrent connections 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 priority available where 1 is the most priority and 9 is the least priority.
weight Number It’s the weight value for the current real server. Backends with more weight will receive more connections. The possible values are from 1 to 9.

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://<zevenet_server>:444/zapi/v4.0/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 the virtual port(s).
max_conns Number It’s the maximum number of concurrent connections 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 priority available where 1 is the most priority and 9 is the least priority.
weight Number It’s the weight value for the current real server. Backends with more weight will receive more connections. The possible values are from 1 to 9.

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 the 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://<zevenet_server>:444/zapi/v4.0/zapi.cgi/farms/l4farm/backends/2

PUT /farms/<farmname>/backends/<id>

Modify the parameters of a backend in for 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 the virtual port(s).
max_conns Number It’s the maximum number of concurrent connections 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 priority available where 1 is the most priority and 9 is the least priority.
weight Number It’s the weight value for the current real server. Backends with more weight will receive more connections. The possible values are from 1 to 9.

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 the 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://<zevenet_server>:444/zapi/v4.0/zapi.cgi/farms/l4farm/backends/1/maintenance

PUT /farms/<farmname>/backends/<id>/maintenance

Set a given action in a backend of an 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 effect 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 the 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://<zevenet_server>:444/zapi/v4.0/zapi.cgi/farms/l4farm/backends/4

DELETE /farms/<farmname>/backends/<id>

Delete a given backend for an 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 creating 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 the 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/v4.0/zapi.cgi/farms/gslbfarm

GET /farms/<farmname>

Show all configuration about a given farm.

Response example:

{
   "description" : "List farm gslbfarm",
   "ipds" : {
      "blacklists" : [],
      "dos" : [],
      "rbl" : [
         {
            "name" : "protection_ssh",
            "status" : "up"
         }
      ]
   },
   "params" : {
      "status" : "needed restart",
      "vip" : "192.168.100.155",
      "vport" : 60
   },
   "services" : [
      {
         "algorithm" : "roundrobin",
         "backends" : [
            {
               "alias" : "localhost",
               "id" : 1,
               "ip" : "127.0.0.1",
               "port" : 53,
               "status" : "up"
            },
            {
               "alias" : "dns-server",
               "id" : 2,
               "ip" : "192.168.55.40",
               "port" : 53,
               "status" : "up"
            },
            {
               "alias" : null,
               "id" : 4,
               "ip" : "192.135.10.2",
               "port" : 53,
               "status" : "up"
            }
         ],
         "deftcpport" : 53,
         "farmguardian" : "dns-request",
         "id" : "service1"
      },
      {
         "algorithm" : "prio",
         "backends" : [
            {
               "alias" : "localhost",
               "id" : 1,
               "ip" : "127.0.0.1",
               "port" : 80,
               "status" : "up"
            },
            {
               "alias" : "localhost",
               "id" : 2,
               "ip" : "127.0.0.1",
               "port" : 80,
               "status" : "up"
            }
         ],
         "deftcpport" : 80,
         "farmguardian" : null,
         "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 Object[] Blacklists applied to the farm.
dos Object[] DoS rules applied to the farm.
rbl Object[] RBL rules applied to the farm.

Blacklist, DoS and RBL Object:

Field Type Description
name String The rule name.
status String Rule status.

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.
farmguardian String It is the FarmGuardian name that is checking the backend status. FarmGuardian will be running while the farm is in up status. Farmguardian logs are not available for GSLB farms
id String Service name which is used as a unique identifier.
algorithm String Type of load balancing algorithm used in the service. The options are: roundrobin, which will balance connections among all up backends, or prio which will send all connections to the first available backend.
deftcpport Number Default TCP port health check. This is the health check TCP port that the service is going to check to determine that the backend service is alive. An empty value is disabled.

Backend object for GSLB farms:

Field Type Description
alias String It is a nick to help to identify the backend. Alias
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 is used as a unique indetifier.
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 on 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/v4.0/zapi.cgi/farms

POST /farms

Create a new GSLB farm.

Request parameters

Field Type Description Required
farmname String Farm name is used as the unique identifier for farms. 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 the 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://<zevenet_server>:444/zapi/v4.0/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. The 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 the 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/v4.0/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 a 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/v4.0/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 identifier 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. 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 priority 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-Passive cluster service with several real servers.

Services object for GSLB farms

Field Type Description
backends Object[] Backends defined in the service.
farmguardian String It is the FarmGuardian name that is checking the backend status. FarmGuardian will be running while the farm is in up status.
id String Service name which is used as the unique identifier.
algorithm String Type of load balancing algorithm used in the service. The options are: roundrobin, which will balance connections among all up backends, or prio which will send all connections to the first available backend.
deftcpport String Default TCP port health check. This is the health check TCP port that the service is going to check 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://<zevenet_server>:444/zapi/v4.0/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 the 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 the 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 the 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://<zevenet_server>:444/zapi/v4.0/zapi.cgi/farms/gslbfarm/services/service1

PUT /farms/<farmname>/services/<id>

Modify the parameters of a GSLB service. id is the service unique identifier that will be modified.

Request parameters

Field Type Description
deftcpport Number This is the health check TCP port that the service is going to check 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 the response example for more information.

Add FarmGuardian

Add FarmGuardian

Request example:

curl -k -X POST -H 'Content-Type: application/json' -H "ZAPI_KEY: <ZAPI_KEY_STRING>"
-d '{"name":"dns-request"}' https://<zevenet_server>:444/zapi/v4.0/zapi.cgi/farms/gslbfarm/service/service1/fg

POST /farms/<farmname>/services/<id>/fg

Apply a FarmGuardian to a service.

The URI parameter is the service unique identifier.

Request parameters

Field Type Description
name String FarmGuardian unique identifier. The FarmGuardians are created and modified in the monitoring section. FarmGuardian logs are not available for gslb farms.

Response example:

{
   "description" : "Add the farm guardian dns-request to the service service1 in the farm gslbfarm",
   "message" : "Success, The farm guardian dns-request was added to the service service1 in the farm gslbfarm"
}

Remove FarmGuardian

Remove FarmGuardian

Request example:

curl -k -X DELETE -H "ZAPI_KEY: <ZAPI_KEY_STRING>"
https://<zevenet_server>:444/zapi/v4.0/zapi.cgi/farms/gslbfarm/service/service1/fg/dns-request

DELETE /farms/<farmname>/fg/<name>

Remove the FarmGuardian from a GSLB service.

Response example:

{
   "description" : "Remove the farm guardian dns-request from the service service1 in the farm gslbfarm",
   "message" : "Sucess, dns-request was removed from the service service1 in the farm gslbfarm"
}

Delete a Service

Delete a Service

Request example:

curl -k -X DELETE -H "ZAPI_KEY: <ZAPI_KEY_STRING>"
https://<zevenet_server>:444/zapi/v4.0/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 that 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 with 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://<zevenet_server>:444/zapi/v4.0/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" : [
      {
         "alias" : "localhost",
         "id" : 1,
         "ip" : "127.0.0.1",
         "port":53,
         "status":"up"
      },
      {
         "alias" : "dns-server",
         "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
alias String It is a nick to help to identify the backend. Alias
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://<zevenet_server>:444/zapi/v4.0/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 the 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://<zevenet_server>:444/zapi/v4.0/zapi.cgi/farms/gslbfarm/services/service1/backends/1

PUT /farms/<farmname>/services/<id>/backends/<id>

Modify the parameters of a backend for a GSLB service.

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 the 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://<zevenet_server>:444/zapi/v4.0/zapi.cgi/farms/gslbfarm/services/service1/backends/3

DELETE /farms/<farmname>/services/<servicename>/backends/<id>

Delete a given backend in a GSLB service.

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://<zevenet_server>:444/zapi/v4.0/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 as the 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 the 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://<zevenet_server>:444/zapi/v4.0/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 the response example for more information.

Delete a Zone

Delete a Zone

Request example:

curl -k -X DELETE -H "ZAPI_KEY: <ZAPI_KEY_STRING>"
https://<zevenet_server>:444/zapi/v4.0/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:

  1. NS. Name Server type record, it delegates a DNS zone to use the given authoritative name servers.
  2. A. Address type record, it returns an IPv4 address of a host.
  3. CNAME. Canonical name type record, it represents an alias of a given name.
  4. 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.
  5. AAAA. Address type record, it returns an IPv6 address of a host.
  6. MX. Mail exchange type record, maps a domain name to a list of message transfer agents for that domain.
  7. SRV. Service locator type record, Generalized service location record, used for newer protocols instead of creating protocol-specific records such as MX.
  8. 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.
  9. PTR. Pointer record, a 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.
  10. 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://<zevenet_server>:444/zapi/v4.0/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 on 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://<zevenet_server>:444/zapi/v4.0/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. It’s 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 on 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 the 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://<zevenet_server>:444/zapi/v4.0/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 on 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 an 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 the response example for more information.

Delete a resource

Delete a resource

Request example:

curl -k -X DELETE -H "ZAPI_KEY: <ZAPI_KEY_STRING>"
https://<zevenet_server>:444/zapi/v4.0/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 creating 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/v4.0/zapi.cgi/farms/dlink

GET /farms/<farmname>

Show all configuration about a farm.

Response example:

{
   "backends" : [
      {
         "alias" : "main-gateway",
         "id" : 0,
         "interface" : "eth0",
         "ip" : "192.168.100.10",
         "priority" : 2,
         "status" : "undefined",
         "weight" : 2
      },
      {
         "alias" : "secondary-gateway",
         "id" : 1,
         "interface" : "eth0",
         "ip" : "192.168.100.11",
         "priority" : 2,
         "status" : "undefined",
         "weight" : 1
      }
   ],
   "description" : "List farm dlink",
   "ipds" : {
      "blacklists" : []
   },
   "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
ipds Object List of IPDS rules applied to this farm.
params Object Parameters of farm configuration.
backends Object[] Real servers created in this farm and its configuration.

IPDS Object:

Field Type Description
blacklists String[] Blacklists applied to the farm.

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 attribute 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
alias String It is a nick to help to identify the backend. Alias
id Number Unique identifier for the backend of 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 configured as a priority 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 configured 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/v4.0/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 creating a farm of type datalink, the key 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 the 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://<zevenet_server>:444/zapi/v4.0/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. The farm must be stopped to modify this field.
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 attribute 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 the 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/v4.0/zapi.cgi/farms/dlink2/ipds/blacklists

POST /farms/<farmname>/ipds/<blacklists>

Apply a blacklist rule to the farm. A datalink profile accepts only blacklist rules.

Request parameters

Field Type Description
name String IPDS rule name used as a unique identifier.

Response example:

{
   "description" : "Apply a rule to a farm",
   "message" : "Blacklist rule china was applied successful to the farm dlink2.",
   "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/v4.0/zapi.cgi/farms/dlink2/ipds/blacklists/china

DELETE /farms/<farmname>/ipds/<blacklists>/<name>

Remove a blacklist rule of the IPDS module from a given farm using its indicator name.

Response example:

{
   "description" : "Delete a rule from a farm",
   "message" : "Blacklist rule china was removed successful from the farm dlink2.",
   "success" : "true"
}

Datalink - Backends

Backends in datalink farms are the gateways through routing the service. The service will multiplexor among these gateways and some of them are 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://<zevenet_server>:444/zapi/v4.0/zapi.cgi/farms/dlink/backends

GET /farms/<farmname>/backends

Get the list of backends in a service.

Response example:

[
   {
      "alias" : "main-gateway",
      "id" : 6,
      "interface" : "eth0",
      "ip" : "192.168.100.10",
      "priority" : 2,
      "status" : "undefined",
      "weight" : 2
   },
   {
      "alias" : "secondary-gateway",
      "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
alias String It is a nick to help to identify the backend. Alias
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 configured as a priority and lower priority will have a 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 configured 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://<zevenet_server>:444/zapi/v4.0/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 configured as a priority and lower priority will have a preference. The default value is 1.
weight Number It’s the weight value for the current backend. It will be used when algorithm field is configured as weight. The 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,"priority":1}'
  https://<zevenet_server>:444/zapi/v4.0/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 backend priority to respond to a certain request.
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",
      "priority" : 1,
      "weight" : 1
   }
}

Response parameters

The response will be a JSON with all requested values updated. See the 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://<zevenet_server>:444/zapi/v4.0/zapi.cgi/farms/dlink/backends/4

DELETE /farms/<farmname>/backends/<id>

Delete a given backend from 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. The rest of the interfaces are based on NICs.

vlan: or virtual LAN card is a kind of network interface that provides network segmentation services. More than one VLAN can be created through a nic interface.

bonding: Also called by other 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 described above and they use the routing tables of its parent interface, so it has to have configured in the same network segment than its parent. This kind of interface should be used for Farms.

List all interfaces

List all interfaces

Request example:

curl -k -X GET -H "ZAPI_KEY: <ZAPI_KEY_STRING>"
https://<zevenet_server>:444/zapi/v4.0/zapi.cgi/interfaces/nic

GET /interfaces

Get a list of interfaces in the system with their configuration.

Response example:

{
   "description" : "List interfaces",
   "interfaces" : [
      {
         "alias" : null,
         "gateway" : "",
         "ip" : "",
         "mac" : "66:eb:31:0e:07:71",
         "name" : "bond2",
         "netmask" : "",
         "status" : "down",
         "dhcp" : "false",
         "type" : "bond"
      },
      {
         "alias" : null,
         "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",
         "dhcp" : "false",
         "type" : "bond"
      },
      {
         "alias" : null,
         "gateway" : "192.168.100.5",
         "has_vlan" : "true",
         "ip" : "192.168.100.241",
         "mac" : "c2:56:f6:54:ff:a0",
         "name" : "eth0",
         "netmask" : "255.255.255.0",
         "status" : "up",
         "dhcp" : "false",
         "type" : "nic",
         "is_slave" : "false"
      },
      {
         "alias" : null,
         "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",
         "dhcp" : "false",
         "type" : "vlan"
      },
      {
         "alias" : null,
         "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"
      },
      {
         "alias" : "gestion",
         "gateway" : "192.168.100.5",
         "has_vlan" : "false",
         "ip" : "192.168.100.102",
         "mac" : "62:30:43:36:29:ac",
         "name" : "eth1",
         "netmask" : "255.255.255.0",
         "status" : "up",
         "dhcp" : "false",
         "type" : "nic",
         "is_slave" : "false"
      },
      {
         "alias" : null,
         "gateway" : "",
         "has_vlan" : "false",
         "ip" : "",
         "mac" : "66:eb:31:0e:07:71",
         "name" : "eth2",
         "netmask" : "",
         "status" : "up",
         "dhcp" : "false",
         "type" : "nic",
         "is_slave" : "true"
      },
      {
         "alias" : null,
         "gateway" : "",
         "has_vlan" : "false",
         "ip" : "",
         "mac" : "a2:6d:80:29:87:c6",
         "name" : "eth3",
         "netmask" : "",
         "status" : "up",
         "type" : "nic",
         "dhcp" : "false",
         "is_slave" : "true"
      }
   ]
}

Response parameters

The response will be a JSON object with an interface object array.

Interface object:

Field Type Description
alias String It is a nick to help to identify the interface. Alias
ip String IP of the interface. IP must be in the same network segment that its parent interface in a virtual interface.
has_vlan String true, the interface it is the parent of a VLAN interface; or false, the interface has not got any VLAN interface appending of it. This field is only for NIC interfaces.
netmask String Netmask of the interface. This value could not be modified in virtual interfaces, it is inherited from parent interface.
gateway String Gateway of the interface. This value could not be modified in virtual interfaces, it is inherited from parent interface.
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 a unique identifier.
status String The values can be up, the interface can receive packets; down, the interface cannot receive packets.
type String The different kind of interfaces are: nic, vlan, virtual or bond.
is_slave String Only available in NIC interfaces, true, the interface is part of a bonding interface, false the interface is not part of a bonding interface.
dhcp String Enables the DHCP service to get the network configuration for the interface from a DHCP server. This parameter accepts: true, to enable the service, the interface configuration will be blocked while the DHCP service is enabled; false to stop the service, the interface will lose all its network configuration.

Retrieve default gateway

Retrieve default gateway

Request example:

curl -k -X GET -H "ZAPI_KEY: <ZAPI_KEY_STRING>"
https://<zevenet_server>:444/zapi/v4.0/zapi.cgi/interfaces/gateway/ipv4

GET /interfaces/gateway/<ip_version>

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.

The system has configured two gateways, once to route IPv4 and another to route IPv6. The URI expects an IP version ipv4 or ipv6.

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 the 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://<zevenet_server>:444/zapi/v4.0/zapi.cgi/interfaces/gateway/ipv4

PUT /interfaces/gateway/<ip_version>

Modify the configuration of the gateway interface.

The URI expects the IP version used in the address field. The possible values are ipv4 and ipv6.

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/<ip_version>

Delete the configuration of the default gateway configuration.

The URI expects one IP version of the default gateway to delete. The possible values are ipv4 and ipv6.

Warning: if the gateway is unset, Zevenet is not going to be reachable from an external network segment.

Delete gateway configuration

Request example:

curl -k -X DELETE -H "ZAPI_KEY: <ZAPI_KEY_STRING>"
https://<zevenet_server>:444/zapi/v4.0/zapi.cgi/interfaces/gateway/ipv4

Response message

If the gateway is unset 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 types 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://<zevenet_server>:444/zapi/v4.0/zapi.cgi/interfaces/nic

Response example:

{
   "description" : "List NIC interfaces",
   "interfaces" : [
      {
         "alias" : null,
         "gateway" : "192.168.100.5",
         "has_vlan" : "true",
         "ip" : "192.168.100.241",
         "is_slave" : "false",
         "mac" : "c2:56:f6:54:ff:a0",
         "name" : "eth0",
         "netmask" : "255.255.255.0",
         "dhcp" : "false",
         "status" : "up"
      },
      {
         "alias" : "gestion",
         "gateway" : "192.168.100.5",
         "has_vlan" : "false",
         "ip" : "192.168.100.102",
         "is_slave" : "false",
         "mac" : "62:30:43:36:29:ac",
         "name" : "eth1",
         "netmask" : "255.255.255.0",
         "dhcp" : "false",
         "status" : "up"
      },
      {
         "alias" : null,
         "gateway" : "",
         "has_vlan" : "false",
         "ip" : "",
         "is_slave" : "false",
         "mac" : "a2:6d:80:29:87:c6",
         "name" : "eth3",
         "netmask" : "",
         "dhcp" : "false",
         "status" : "down"
      }
   ]
}

Response parameters

The response will be a JSON object with an array of NIC interface objects.

NIC interface object:

Field Type Description
alias String It is a nick to help to identify the interface. Alias
ip String IP of the interface.
has_vlan String true, the interface it is the parent of a VLAN interface; or false, the interface has not got any VLAN interface appending of it.
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 identifier. It is unmodifiable.
name String Interface’s name. It is used as an interface unique identifier.
status String The values can be up, the interface can receive packets; down, the interface cannot receive packets.
is_slave String true the interface is part of a bonding interface, false the interface is not part of a bonding interface.
dhcp String Enables the DHCP service to get the network configuration for the interface from a DHCP server. This parameter accepts: true, to enable the service, the interface configuration will be blocked while the DHCP service is enabled; false to stop the service, the interface will lose all its network configuration.

Retrieve NIC interface

Retrieve NIC interface

Request example:

curl -k -X GET -H "ZAPI_KEY: <ZAPI_KEY_STRING>"
https://<zevenet_server>:444/zapi/v4.0/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" : {
      "alias" : "gestion",
      "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",
      "dhcp" : "false",
      "status" : "up"
   }
}

Response parameters

Field Type Description
alias String It is a nick to help to identify the interface. Alias
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 identifier. It is unmodifiable.
name String Interface’s name. It is used as an interface unique identifier.
status String The values can be up, the interface can receive packets; down, the interface cannot receive packets.
type String The different kind of interfaces is: nic, vlan, virtual or bond. Each one is 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.
dhcp String Enables the DHCP service to get the network configuration for the interface from a DHCP server. This parameter accepts: true, to enable the service, the interface configuration will be blocked while the DHCP service is enabled; false to stop the service, the interface will lose all its network configuration.

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://<zevenet_server>:444/zapi/v4.0/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.
force String If a farm is using the interface, the interface won’t be able to be modified. Then, if this parameter is sent with the value true, the interface will be forced to take the new configuration and all farms are using the interface will be restarted.
dhcp String Enables the DHCP service to get the network configuration for the interface from a DHCP server. This parameter accepts: true, to enable the service, the interface configuration will be blocked while the DHCP service is enabled; false to stop the service, the interface will lose all its network configuration.

Response example:

{
   "description" : "Configure nic interface",
   "params" : {
      "gateway" : "192.168.100.5",
      "ip" : "192.168.100.102",
      "netmask" : "255.255.255.0",
      "force" : "true"
   }
}

Response parameters

The response will be a JSON with all requested values updated. See the response example for more information.

Delete NIC configuration

Delete NIC configuration

Request example:

curl -k -X DELETE -H "ZAPI_KEY: <ZAPI_KEY_STRING>"
https://<zevenet_server>:444/zapi/v4.0/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://<zevenet_server>:444/zapi/v4.0/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 the response example for more information.

Network - VLAN interfaces

VLAN interface lets a NIC or bonding interface works in another network, so the networking configuration (IP, gateway, and netmask) has to be in a different network segment. 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://<zevenet_server>:444/zapi/v4.0/zapi.cgi/interfaces/vlan

GET /interfaces/vlan

Get all parameters of VLAN interfaces.

Response example:

{
   "description" : "List VLAN interfaces",
   "interfaces" : [
      {
         "alias" : null,
         "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",
         "dhcp" : "false",
         "status" : "down"
      }
   ]
}

Response parameters

The response will be a JSON object with a VLAN interface object array.

The VLAN parameters are:

Field Type Description
alias String It is a nick to help to identify the interface. Alias
ip String IP of the interface. It can be different from the parent interface 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 a unique identifier. This name is a chain formatted 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 cannot receive packets.
dhcp String Enables the DHCP service to get the network configuration for the interface from a DHCP server. This parameter accepts: true, to enable the service, the interface configuration will be blocked while the DHCP service is enabled; false to stop the service, the interface will lose all its network configuration.

Retrieve VLAN interface

Retrieve VLAN interface

Request example:

curl -k -X GET -H "ZAPI_KEY: <ZAPI_KEY_STRING>"
https://<zevenet_server>:444/zapi/v4.0/zapi.cgi/interfaces/vlan/eth0.1

GET /interfaces/vlan/<name>

Get all the parameters of the VLAN interface. name is the interface unique identifier.

Response example:

{
   "description" : "Show VLAN interface",
   "interface" : {
      "alias" : null,
      "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",
      "dhcp" : "false",
      "status" : "up"
   }
}

Response parameters

Field Type Description
alias String It is a nick to help to identify the interface. Alias
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 a unique identifier. This name is a chain formatted 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 cannot receive packets.
dhcp String Enables the DHCP service to get the network configuration for the interface from a DHCP server. This parameter accepts: true, to enable the service, the interface configuration will be blocked while the DHCP service is enabled; false to stop the service, the interface will lose all its network configuration.

Create a 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","mac":"52:98:19:6a:c9:18","dhcp":"false"}'
https://<zevenet_server>:444/zapi/v4.0/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 from the parent interface 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 a unique identifier. This name is a chain formatted by a parent interface name, a dot character “.” and a number for the VLAN network interface. true
dhcp String Enables the DHCP service to get the network configuration for the interface from a DHCP server. This parameter accepts: true, to enable the service, the interface configuration will be blocked while the DHCP service is enabled; false to stop the service, the interface will lose all its network configuration.
mac String Rewrites the MAC of the interface.

Response example:

{
   "description" : "Add a vlan interface",
   "params" : {
      "gateway" : "192.168.120.1",
      "ip" : "192.168.120.120",
      "mac" : "52:98:19:6a:c9:18",
      "name" : "eth0.1",
      "dhcp" : "false",
      "netmask" : "255.255.255.0"
   }
}

Response parameters

The response will be a JSON with all requested values updated. See the 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","mac":"96:23:25:8b:d4:af"}'
https://<zevenet_server>:444/zapi/v4.0/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 from the parent interface IP.
netmask String Define the network segment where the interface is working.
gateway String IP used to send packets of a different network segment.
dhcp String Enables the DHCP service to get the network configuration for the interface from a DHCP server. This parameter accepts: true, to enable the service, the interface configuration will be blocked while the DHCP service is enabled; false to stop the service, the interface will lose all its network configuration.
mac String Rewrites the MAC of the interface.
force String If a farm is using the interface, the interface won’t be able to be modified. Then, if this parameter is sent with the value true, the interface will be forced to take the new configuration and all farms are using the interface will be restarted.

Response example:

{
   "description" : "Modify VLAN interface",
   "params" : {
      "gateway" : "192.168.131.1",
      "ip" : "192.168.131.155",
      "netmask" : "255.255.255.0",
      "mac" : "96:23:25:8b:d4:af",
      "dhcp" : "false",
      "force" : "true"
   }
}

Response parameters

The response will be a JSON with all requested values updated. See the response example for more information.

Delete VLAN interface

Delete VLAN interface

Request example:

curl -k -X DELETE -H "ZAPI_KEY: <ZAPI_KEY_STRING>"
https://<zevenet_server>:444/zapi/v4.0/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://<zevenet_server>:444/zapi/v4.0/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 the response example for more information.

Network - Virtual interfaces

Network interfaces let users set another network interface in the same networking segment than their parents, so virtual interfaces always inherit the network configuration from its parent. The different parameter will be the ip. The 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 identity for the virtual interface.

List Virtual interfaces

List Virtual interfaces

Request example:

curl -k -X GET -H "ZAPI_KEY: <ZAPI_KEY_STRING>"
https://<zevenet_server>:444/zapi/v4.0/zapi.cgi/interfaces/virtual

GET /interfaces/virtual

Get all the parameters of virtual interfaces.

Response example:

{
   "description" : "List virtual interfaces",
   "interfaces" : [
      {
         "alias" : null,
         "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"
      },
      {
         "alias" : null,
         "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
alias String It is a nick to help to identify the interface. Alias
ip String IP of the interface. The IP must be in the same network segment that the parent interface.
netmask String Define the network segment where the interface is working. It inherits from the parent interface.
gateway String IP used to send packets of a different network segment. It inherits from the parent interface.
mac String MAC of the interface. It inherits from the parent interface.
name String Interface’s name. It is used as a unique identifier. This name is a chain formatted 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 cannot receive packets.

Retrieve virtual interface

Retrieve virtual interface

Request example:

curl -k -X GET -H "ZAPI_KEY: <ZAPI_KEY_STRING>"
https://<zevenet_server>:444/zapi/v4.0/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" : {
      "alias" : null,
      "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
alias String It is a nick to help to identify the interface. Alias
ip String IP of the interface. The IP must be in the same network segment that the parent interface.
netmask String Define the network segment where the interface is working. It inherits from the parent interface.
gateway String IP used to send packets of a different network segment. It inherits from the parent interface.
mac String MAC of the interface. It inherits from the parent interface.
name String Interface’s name. It is used as a unique identifier. This name is a chain formatted 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 cannot receive packets.

Create a 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://<zevenet_server>:444/zapi/v4.0/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 the same network segment that the parent interface. true
name String Interface’s name. It is used as a unique identifier. This name is a chain formatted 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 the response example for more information.

Field Type Description
ip String IP of the interface. The IP must be in the same network segment that the parent interface.
netmask String Define the network segment where the interface is working. It inherits from the parent interface.
gateway String IP used to send packets to a different network segment. It inherits from the parent interface.
mac String MAC of the interface. It inherits from the parent interface.
name String Interface’s name. It is used as a unique identifier. This name is a chain formatted by a parent interface, a colon character “:” and an alphanumeric 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://<zevenet_server>:444/zapi/v4.0/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 required
ip String IP of the interface. The IP must be in the same network segment that the parent interface. true
force String If a farm is using the interface, the interface won’t be able to be modified. Then, if this parameter is sent with the value true, the interface will be forced to take the new configuration and all farms are using the interface will be restarted.

Response example:

{
   "description" : "Modify virtual interface",
   "params" : {
      "ip" : "192.168.100.10",
      "force" : "true"
   }
}

Response parameters

The response will be a JSON with all requested values updated. See the response example for more information.

Delete virtual interface

Delete virtual interface

Request example:

curl -k -X DELETE -H "ZAPI_KEY: <ZAPI_KEY_STRING>"
https://<zevenet_server>:444/zapi/v4.0/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://<zevenet_server>:444/zapi/v4.0/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 the response example for more information.

Network - Bonding interfaces

The Linux bonding interface or also called by other 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 it.

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:

  1. Network interface support in the base drivers for retrieving the speed and duplex of each slave.

  2. 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://<zevenet_server>:444/zapi/v4.0/zapi.cgi/interfaces/bonding

GET /interfaces/bonding

Get configuration about all bonding interfaces in the system.

Response example:

{
   "description" : "List bonding interfaces",
   "interfaces" : [
      {
         "alias" : null,
         "gateway" : "",
         "ip" : "",
         "mac" : "66:eb:31:0e:07:71",
         "mode" : "broadcast",
         "name" : "bond2",
         "netmask" : "",
         "dhcp" : "false",
         "slaves" : [
            {
               "name" : "eth2"
            }
         ],
         "status" : "down"
      },
      {
         "alias" : null,
         "gateway" : "192.168.100.1",
         "ip" : "192.168.100.121",
         "mac" : "a2:6d:80:29:87:c6",
         "mode" : "balance-rr",
         "name" : "bondiface",
         "dhcp" : "false",
         "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
alias String It is a nick to help to identify the interface. Alias
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 identifier. It is the mac of the first NIC interface slave.
name String Interface’s name. It is used as an 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 interface.
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.
dhcp String Enables the DHCP service to get the network configuration for the interface from a DHCP server. This parameter accepts: true, to enable the service, the interface configuration will be blocked while the DHCP service is enabled; false to stop the service, the interface will lose all its network configuration.

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://<zevenet_server>:444/zapi/v4.0/zapi.cgi/interfaces/bonding/bondiface

GET /interfaces/bonding/<name>

Get all the parameters of the interface. name is the interface unique identifier.

Response example:

{
   "description" : "Show bonding interface",
   "interface" : {
      "alias" : null,
      "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",
      "dhcp" : "false",
      "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
alias String It is a nick to help to identify the interface. Alias
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 identifier. It is the mac of the first NIC interface slave.
name String Interface’s name. It is used as an 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 interface.
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.
dhcp String Enables the DHCP service to get the network configuration for the interface from a DHCP server. This parameter accepts: true, to enable the service, the interface configuration will be blocked while the DHCP service is enabled; false to stop the service, the interface will lose all its network configuration.

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://<zevenet_server>:444/zapi/v4.0/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 an 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 identifier. It is the mac of the first NIC interface slave.
name String Interface’s name. It is used as an 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 that build the bonding interface.
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","mac":"86:2f:0e:9a:30:14"}'
https://<zevenet_server>:444/zapi/v4.0/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.
force String If a farm is using the interface, the interface won’t be able to be modified. Then, if this parameter is sent with the value true, the interface will be forced to take the new configuration and all farms are using the interface will be restarted.
dhcp String Enables the DHCP service to get the network configuration for the interface from a DHCP server. This parameter accepts: true, to enable the service, the interface configuration will be blocked while the DHCP service is enabled; false to stop the service, the interface will lose all its network configuration.
mac String Rewrites the MAC of the interface.

Response example:

{
   "description" : "Modify bond address",
   "params" : {
      "gateway" : "192.168.100.1",
      "ip" : "192.168.100.121",
      "netmask" : "255.255.255.0",
      "mac" : "86:2f:0e:9a:30:14",
      "dhcp" : "false",
      "force" : "true"
   }
}

Response parameters

The response will be a JSON with all requested values updated. See the response example for more information.

Delete Bonding configuration

Delete Bonding configuration

Request example:

curl -k -X DELETE -H "ZAPI_KEY: <ZAPI_KEY_STRING>"
https://<zevenet_server>:444/zapi/v4.0/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://<zevenet_server>:444/zapi/v4.0/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 the 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://<zevenet_server>:444/zapi/v4.0/zapi.cgi/interfaces/bonding/bondiface/slaves

POST /interfaces/bonding/<name>/slaves

Add a NIC interface as a 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 the 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 the 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://<zevenet_server>:444/zapi/v4.0/zapi.cgi/interfaces/bonding/bondiface/slaves/eth2

DELETE /interfaces/bonding/<name>/slaves/<name>

Delete a NIC slave interface from a bonding interface. The 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 - 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 behavior 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://<zevenet_server>:444/zapi/v4.0/zapi.cgi/interfaces/floating

GET /interfaces/floating

Show all available or configurated interfaces where a floating IP has been created.

Response example:

{
   "description" : "List floating interfaces",
   "params" : [
      {
         "alias" : null,
         "floating_alias" : null,
         "floating_ip" : null,
         "interface" : "bondiface",
         "interface_virtual" : null
      },
      {
         "alias" : null,
         "floating_alias" : null,
         "floating_ip" : "192.168.100.41",
         "interface" : "eth0",
         "interface_virtual" : "eth0:virtiface"
      },
      {
         "alias" : null,
         "floating_alias" : null,
         "floating_ip" : null,
         "interface" : "eth0.1",
         "interface_virtual" : null
      },
      {
         "alias" : "gestion",
         "floating_alias" : 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
alias String It is a nick to help to identify the interface. Alias
floating_alias String It is the alias of the virtual interface.
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://<zevenet_server>:444/zapi/v4.0/zapi.cgi/interfaces/floating/eth0

GET /interfaces/floating/<name>

Shows if an interface has a configured floating IP. If it has one configurated 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" : {
      "alias" : null,
      "floating_alias" : null,
      "floating_ip" : "192.168.100.41",
      "interface" : "eth0",
      "interface_virtual" : "eth0:virtiface"
   }
}

Response parameters

Field Type Description
alias String It is a nick to help to identify the interface. Alias
floating_alias String It is the alias of the virtual interface.
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://<zevenet_server>:444/zapi/v4.0/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://<zevenet_server>:444/zapi/v4.0/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"
}

Network - Aliases

Put an alias to an interface or a backend to identifies it quickly.

Two types of aliases exist, interface alias can be applied in all types of interfaces: NIC, bonding, VLAN or virtual. It is an easy way of relating an interface name with a more friendly name.

The other type of alias is for backends. This relates the backend IP with an alias.

The aliases are only visual information, it does not replace the backend IP or the interface name in a ZAPI request.

List aliases

List aliases

Request example:

curl -k -X GET -H "ZAPI_KEY: <ZAPI_KEY_STRING>"
https://<zevenet_server>:444/zapi/v4.0/zapi.cgi/aliases/backends

GET /aliases/<backends|interfaces>

List the aliases in the system for interfaces or backends.

Response example:

{
   "description" : "List the aliases",
   "params" : [
      {
         "id" : "192.168.11.13",
         "alias" : "http-backend"
      },
      {
         "id" : "127.0.0.1",
         "alias" : "localhost"
      }
   ]
}

Response parameters

The ZAPI returns a hash where the key is the backend IP or the interface name and the value is its alias.

Create or modify an alias

Create or modify an alias

Request example:

curl -k -X PUT -H 'Content-Type: application/json' -H "ZAPI_KEY: <ZAPI_KEY_STRING>"
-d '{"alias":"management"}'
https://<zevenet_server>:444/zapi/v4.0/zapi.cgi/aliases/interfaces/eth0

PUT /aliases/<backends|interfaces>/<id>

If the object has an alias, it will be replaced, else an alias will be created for the object.

The id URI parameter is the backend IP or the interface name.

Request parameters

Field Type Description
alias String It is the nick for the element id sent in the URI.

Response example:

{
   "description" : "Set an alias",
   "message" : "Alias for eth0 has been updated successfully",
   "success" : "true"
}

Response parameters

The ZAPI returns a success message if the process was correct.

Delete an alias

Delete an alias

Request example:

curl -k -X DELETE -H "ZAPI_KEY: <ZAPI_KEY_STRING>"
https://<zevenet_server>:444/zapi/v4.0/zapi.cgi/aliases/interfaces/eth0

DELETE /aliases/<backends|interfaces>/<id>

It deletes the alias of an interface or backend.

The id URI parameter is the backend IP or the interface name.

Response example:

{
   "description" : "Delete an alias",
   "message" : "The alias has been deleted.",
   "success" : "true"
}

Response parameters

The ZAPI returns a success message if the process was correct.

Monitoring - FarmGuardian

FarmGuardian is used for advanced monitoring state of backends. When a problem is detected by FarmGuardian automatically disables the real server and will be marked as blacklisted.

List FarmGuardians

List FarmGuardians

Request example:

curl -k -X GET -H "ZAPI_KEY: <ZAPI_KEY_STRING>"
https://<zevenet_server>:444/zapi/v4.0/zapi.cgi/monitoring/fg

GET /monitoring/fg

List the FarmGuardians. Templates and custom FarmGuardians appear this the list.

Response example:

{
   "description" : "List farm guardian checks and templates",
   "params" : [
      {
         "command" : "check_tcp -p PORT -H HOST",
         "cut_conns" : "false",
         "description" : "It does a TCP connection to test if the backend is alive",
         "farms" : [],
         "interval" : 5,
         "log" : "false",
         "name" : "check_tcp-cut_conns",
         "template" : "true"
      },
      {
         "command" : "check_tcp -p 80 -H HOST",
         "cut_conns" : "false",
         "description" : "TCP check to the port 80",
         "farms" : [
                     "web_service",
                     "my_welcome_web"
         ],
         "interval" : 7,
         "log" : "true",
         "name" : "custom-tcp",
         "template" : "false"
      },
      {
         "command" : "check_tcp -p PORT -H HOST",
         "cut_conns" : "false",
         "description" : "It does a TCP connection to test if the backend is alive",
         "farms" : [],
         "interval" : 5,
         "log" : "false",
         "name" : "check_tcp",
         "template" : "true"
      }
   ]
}

Response parameters

The response will be a JSON object with the key params and the format below:

Field Type Description
command String Command to check the service status in the backend. Those available commands are in libexec path.
cut_conns String The possible values are: true, FarmGuardian cuts the current connections when the backend is not available; or false, if the backend it is not available, it will be disabled but the alive sessions continue.
description String Brief description of the check.
farms String[] Farms where the FarmGuardian is applied.
interval Number Time between checks.
log String The possible values are: true, FarmGuardian will log each check; or false, if the backend it is not available, it will be disabled but the alive sessions continue.
name String Unique identifier.
template String If the FarmGuardian is a template, it won’t be applied to any farm. The templates are useful to create a new FarmGuardian.

Retrieve a FarmGuardian

Retrieve a FarmGuardian

Request example:

curl -k -X GET -H "ZAPI_KEY: <ZAPI_KEY_STRING>"
https://<zevenet_server>:444/zapi/v4.0/zapi.cgi/monitoring/fg/check_tcp

GET /monitoring/fg/<name>

Show the configuration of a FarmGuardian.

The URI parameter name is the FarmGuardian unique identifier.

Response example:

{
   "description" : "Retrive the farm guardian check_tcp",
   "params" : {
      "command" : "check_tcp -p PORT -H HOST",
      "cut_conns" : "false",
      "description" : "It does a TCP connection to test if the backend is alive",
      "farms" : [],
      "interval" : 5,
      "log" : "false",
      "name" : "check_tcp",
      "template" : "true"
   }
}

Response parameters

The response will be a JSON object with the key params and the format below:

Field Type Description
command String Command to check the service status in the backend. Those available commands are in libexec path.
cut_conns String The possible values are: true, FarmGuardian cuts the current connections when the backend is not available; or false, if the backend it is not available, it will be disabled but the alive sessions continue.
description String Brief description of the check.
farms String[] Farms where the FarmGuardian is applied.
interval Number Time between checks.
log String The possible values are: true, FarmGuardian will log each check; or false, if the backend it is not available, it will be disabled but the alive sessions continue.
name String Unique identifier.
template String If the FarmGuardian is a template, it won’t be modified. The templates are useful to create a new FarmGuardian or apply directly to farms.

Create a FarmGuardian

Create a FarmGuardian

Request example:

curl -k -X POST -H 'Content-Type: application/json' -H "ZAPI_KEY: <ZAPI_KEY_STRING>"
-d '{"name":"check_tcp-cut_conns", "copy_from":"check_tcp"}'
https://<zevenet_server>:444/zapi/v4.0/zapi.cgi/monitoring/fg

POST /monitoring/fg

Create a new FarmGuardian.

Request parameters

The response will be a JSON object with the key params and the format below:

Field Type Description Required
name String Unique identifier. true
copy_from String It is the FarmGuardian used as a template to create the new FarmGuardian. If this field is not sent, the new FarmGuardian is created without configuration.

Response example:

{
   "description" : "Create a farm guardian check_tcp-cut_conns",
   "message" : "The farm guardian check_tcp-cut_conns has been created successfully",
   "params" : {
      "command" : "check_tcp -p PORT -H HOST",
      "cut_conns" : "false",
      "description" : "It does a TCP connection to test if the backend is alive",
      "farms" : [],
      "interval" : 5,
      "log" : "false",
      "name" : "check_tcp-cut_conns",
      "template" : "true"
   }
}

Response parameters

The response will be a JSON object with the key params and the format below:

Field Type Description
command String Command to check the service status in the backend. Those available commands are in libexec path.
cut_conns String The possible values are: true, FarmGuardian cuts the current connections when the backend is not available; or false, if the backend it is not available, it will be disabled but the alive sessions continue.
description String Brief description of the check.
farms String[] Farms where the FarmGuardian is applied.
interval Number Time between checks.
log String The possible values are: true, FarmGuardian will log each check; or false, if the backend it is not available, it will be disabled but the alive sessions continue.
name String Unique identifier.
template String If the FarmGuardian is a template, it won’t be modified. The templates are useful to create a new FarmGuardian or apply directly to farms.

Modify a FarmGuardian

Modify a FarmGuardian

Request example:

curl -k -X PUT -H 'Content-Type: application/json' -H "ZAPI_KEY: <ZAPI_KEY_STRING>"
-d '{"interval":7,"log":"true","description":"TCP check to the port 80","command":"check_tcp -p 80 -H HOST","cut_conns":"false"}'
https://<zevenet_server>:444/zapi/v4.0/zapi.cgi/monitoring/fg/custom-tcp

PUT /monitoring/fg/<name>

Modify a FarmGuardian.

The URI parameter name is the FarmGuardian unique identifier.

Request parameters

The response will be a JSON object with the key params and the format below:

Field Type Description Required
command String Command to check the service status in the backend. Those available commands are in libexec path.
cut_conns String The possible values are: true, FarmGuardian cuts the current connections when the backend is not available; or false, if the backend it is not available, it will be disabled but the alive sessions continue.
description String Brief description of the check.
interval Number Time between checks.
log String The possible values are: true, FarmGuardian will log each check; or false, if the backend it is not available, it will be disabled but the alive sessions continue.
force String If a running farm is using the FarmGuardian, FarmGuardian won’t be able to be modified. Then, if this parameter is sent with the value true, the FarmGuardian will be forced to take the new configuration.

Response example:

{
   "description" : "Modify farm guardian custom-tcp",
   "message" : "Success, some parameters have been changed in farm guardian custom-tcp.",
   "params" : {
      "command" : "check_tcp -p 80 -H HOST",
      "cut_conns" : "false",
      "description" : "TCP check to the port 80",
      "farms" : [],
      "interval" : 7,
      "log" : "true",
      "name" : "custom-tcp",
      "template" : "false"
   }
}

Response parameters

The response will be a JSON object with the key params and the format below:

Field Type Description
command String Command to check the service status in the backend. Those available commands are in libexec path.
cut_conns String The possible values are: true, FarmGuardian cuts the current connections when the backend is not available; or false, if the backend it is not available, it will be disabled but the alive sessions continue.
description String Brief description of the check.
farms String[] Farms where the FarmGuardian is applied.
interval Number Time between checks.
log String The possible values are: true, FarmGuardian will log each check; or false, if the backend it is not available, it will be disabled but the alive sessions continue.
name String Unique identifier.
template String If the FarmGuardian is a template, it won’t be applied to any farm. The templates are useful to create a new FarmGuardian.

Delete a FarmGuardian

Delete a FarmGuardian

Request example:

curl -k -X DELETE -H 'Content-Type: application/json' -H "ZAPI_KEY: <ZAPI_KEY_STRING>"
https://<zevenet_server>:444/zapi/v4.0/zapi.cgi/monitoring/fg/custom-tcp

DELETE /monitoring/fg/<name>

DELETE a FarmGuardian.

The URI parameter name is the FarmGuardian unique identifier.

Response example:

{
   "description" : "Delete the farm guardian custom-tcp",
   "message" : "custom-tcp has been deleted successful.",
   "success" : "true"
}

Monitoring - Statistics

Show information about the system and farms. This information will be useful to monitor 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/v4.0/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 does not use by any program.
iowait Number CPU used by input or output process.
irq Number CPU used by hardware interruptions.
nice Number CPU scheduling priority.
softirq Number CPU used by software interruptions.
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 percentage the last minute.
Last_5 Number Load system percentage five minutes ago.
Last_15 Number Load system percentage 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 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/v4.0/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 following 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 traffic in MB.

Show interfaces statistics

Show interfaces statistics

Request example:

curl -k -X GET -H "ZAPI_KEY: <ZAPI_KEY_STRING>"
https://<zevenet_server>:444/zapi/v4.0/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 a 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 a 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/v4.0/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 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/v4.0/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 in the last five minutes.
Last_15 Number Load system usage the last fifteen 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/v4.0/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 does not use by any program.
iowait Number CPU used by input or output process.
irq Number CPU used by hardware interruptions.
nice Number CPU scheduling priority.
softirq Number CPU used by software interruptions.
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/v4.0/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.

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/v4.0/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/v4.0/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 the total number of currently 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 farm statistics

Show farm statistics

Request example:

curl -k -X GET -H "ZAPI_KEY: <ZAPI_KEY_STRING>"
https://<zevenet_server>:444/zapi/v4.0/zapi.cgi/stats/farms/farmname

GET /stats/farms/<farmname>

Shows the current farm status, their backend status and connections. Each farm will response with a different object, depending on 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 The 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 a 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 maintenance 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 depends on 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 to 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 a 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 requests 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 domain name.
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 requests 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" : 1,
         "id" : 5,
         "ip" : "192.168.5.100",
         "pending" : 0,
         "port" : "8080",
         "status" : "up"
      }
   ],
   "description" : "List farm stats",
   "sessions" : [
      {
         "id" : 5,
         "session" : "192.168.5.100"
      }
   ]

}

Response parameters in L4xNAT farms

The response will be a JSON with object backends and sessions:

Backend object:

Field Type Description
established Number The total number of currently 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 maintenance tasks; undefined, the backend status has been not checked.

Session object:

Field Type Description
id Number Backend unique identifier where the client is assigned.
session String Session unique identifier. It is the client IP.

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/v4.0/zapi.cgi/stats/farms/modules

GET /stats/farms/modules

Get a summary of statistic modules. This call shows each module status, the number of configured, the number of farms put down and up.

The definition of 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 the system administrator.
problem Number Number of farms in problem status. The farm is a 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 maintenance 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/v4.0/zapi.cgi/stats/farms/modules/lslb

GET /stats/farms/modules/<module>

Show farm 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 The total number of currently established connections.
farmname String Farm name, a 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 themselves 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 monitor the internal load balancer system to detect problems through the parameters of CPU usage, swap memory, RAM, all configured network interfaces, load and hard disk storage.

Also, you’ll be able to access the weekly, monthly and yearly history.

Graphs with information are responded in the 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/v4.0/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 available.
interfaces String[] List of interface graphs available.
system Object[] List of system graphs available. The array has an object with an array wich indicates disk mount points.

System object:

The system object contains an array list related to the system and a disk objects 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/v4.0/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/v4.0/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/v4.0/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 Period used to generate the graph. The possible values are: daily, weekly, monthly or yearly.
graphs String Graph in base64 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/v4.0/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/v4.0/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/v4.0/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 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 base64 format.

IPDS

This module is the implementation of an 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 an object of different natures. Each one offers a solution for external malicious or suspicious activity. This tool helps system administrators controlling threats and attacks.

The available rules to apply to Zevenet can be blacklists, DoS, RBL or WAF.

Retrieve IPDS package

Retrieve IPDS package

Request example:

curl -k -X GET -H "ZAPI_KEY: <ZAPI_KEY_STRING>"
https://<zevenet_server>:444/zapi/v4.0/zapi.cgi/ipds/package

GET /ipds/package

Retrieve the zevenet-ipds package information. This package contains updated rules for each IPDS module.

Response example:

{
   "description" : "zevenet-ipds package status info",
   "params" : {
      "frequency" : 0,
      "mode" : "disabled",
      "ruleset_date" : "05-06-2019",
      "scheduled" : "none",
      "status" : "Updates available",
      "time" : {
         "hour" : 0,
         "minute" : 0
      }
   }
}

Response parameters

The response will be a JSON object with a key set to params, its value will be the information of the IPDS package.

Field Type Description
status String Shows the update status information about the IPDS package. If the package is installed, if it is updated and if there are pending updates.
ruleset_date String It is the date when the package was built. It is not the installed date.
scheduled String Descriptive message explains the schedule configuration.
mode String It indicates how often the update will happen or to disable the schedule. The available values are: Daily Schedule the update to be done each day, it enables the Frequency field to indicate how many hours will the update be repeated, from the time set; Weekly, Schedule the update to be done once a week, it enables the frequency as Day of the week to indicate which day of the week will the update be scheduled (from Monday to Sunday); monthly, schedule the update to be done once a month.
frequency Number If mode is daily, frequency is the number of hours between package update from time; If mode is weekly, the expected value is the number weekday (from Monday, 1, to Sunday, 7); If mode is monthly, the expected value is the number month day (from 1 to 31).
time Object Allows to set at which time will the update occur or from which time will the package be updated if the mode is set as Daily and Frequency is greater than 0.

Time object:

This object, hour:minute, is the hour when the package will be updated.

Field Type Description
hour Number Is the hour in format form 0 to 23.
minute Number are the minutes in format form 0 to 59.

Apply an action to IPDS package

Apply an action to IPDS package

Request example for updating the IPDS rules:

curl -k -X POST -H "ZAPI_KEY: <ZAPI_KEY_STRING>" -H 'Content-Type: application/json'
-d '{"action":"upgrade"}'
https://<zevenet_server>:444/zapi/v4.0/zapi.cgi/ipds/package

Response example:

{
   "desc" : "Execute an action over the zevenet-ipds package",
   "params" : {
      "ruleset_date" : "07-06-2019",
      "status" : "Installed and updated"
   }
}

Request example for scheduling updates:

curl -k -X POST -H "ZAPI_KEY: <ZAPI_KEY_STRING>" -H 'Content-Type: application/json'
-d '{"mode":"daily","frequency":1,"time":{"hour":0,"minute":0},"action":"schedule"}'
https://<zevenet_server>:444/zapi/v4.0/zapi.cgi/ipds/package

Response example:

{
   "desc" : "Execute an action over the zevenet-ipds package",
   "params" : {
      "frequency" : 1,
      "mode" : "daily",
      "scheduled" : "daily from 0:00 to 23:00 each 1 hours",
      "status" : "Installed and updated",
      "time" : {
         "hour" : 0,
         "minute" : 0
      }
   }
}

POST /ipds/package

Apply action about the zevenet-ipds package.

Request parameters

Field Type Description Required
action String It is the action to apply regarding the IPDS rules package. The options are: upgrade to force an upgrade of the package. schedule to configure the system upgrades the package with a periodicity.
mode String It indicates how often the update will happen or to disable the schedule. The available values are: Daily Schedule the update to be done each day, it enables the Frequency field to indicate how many hours will the update be repeated, from the time set; Weekly, Schedule the update to be done once a week, it enables the frequency as Day of the week to indicate which day of the week will the update be scheduled (from Monday to Sunday); monthly, schedule the update to be done once a month.
frequency Number If mode is daily, frequency is the number of hours between package update form time; If mode is weekly, the expected value is the number weekday (from Monday, 1, to Sunday, 7); If mode is monthly, the expected value is the number month day (from 1 to 31).
time Object Allows to set at which time will the update occur or from which time will the package be updated if the mode is set as Daily and Frequency is greater than 0.

Time object:

This object, hour:minute, is the hour when the package will be updated.

Field Type Description
hour Number Is the hour in format form 0 to 23.
minute Number are the minutes in format form 0 to 59.

Response parameters

The response will be a JSON object with a key set to params. The value of this will be the information about the IPDS package.

Field Type Description
status String Shows the update status information about the IPDS package. If the package is installed, if it is updated and if there are pending updates.
ruleset_date String It is the date when the package was built. It is not the installed date.
scheduled String Descriptive message explains the schedule configuration.
mode String It indicates how often the update will happen or to disable the schedule. The available values are: Daily Schedule the update to be done each day, it enables the Frequency field to indicate how many hours will the update be repeated, from the time set; Weekly, Schedule the update to be done once a week, it enables the frequency as Day of the week to indicate which day of the week will the update be scheduled (from Monday to Sunday); monthly, schedule the update to be done once a month.
frequency Number If mode is daily, frequency is the number of hours between package update from time; If mode is weekly, the expected value is the number weekday (from Monday, 1, to Sunday, 7); If mode is monthly, the expected value is the number month day (from 1 to 31).
time Object Allows to set at which time will the update occur or from which time will the package be updated if the mode is set as Daily and Frequency is greater than 0.

Time object:

This object, hour:minute, is the hour when the package will be updated.

Field Type Description
hour Number Is the hour in format form 0 to 23.
minute Number are the minutes in format form 0 to 59.

List all IPDS rules

List ipds rules

Request example:

curl -k -X GET -H "ZAPI_KEY: <ZAPI_KEY_STRING>"
https://<zevenet_server>:444/zapi/v4.0/zapi.cgi/ipds

GET /ipds

List all IPDS rules that exist 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 contains the key attributes below.

Field Type Description
name String IPDS rule name. It is used as a 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 apply to a farm.

IPDS - Blacklists

Blacklists lets users use lists to filter or allow traffic according to source IPs (Incoming traffic).

There are two types of lists:

  1. Remotes: Lists are obtained from a URL, those lists are not modifiable and can be scheduled to be downloaded.
  2. Local: Users can create their lists with a given policy, deny if the incoming IP matches then the traffic will be rejected or allow if the incoming IP matches then the traffic will be allowed.

This module includes preloaded lists provided by Zevenet team, the list is ready to be applied to farms. Additionally, users can create their personalized lists.

Several lists can be applied to the same farm if the source IP matches in some of the lists the traffic will be allowed or denied depending on the blacklist policy. At the moment the IP matches then no more blacklist checks are done to the source IP.

If a source IP is in two different lists, one of type deny and the 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://<zevenet_server>:444/zapi/v4.0/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 contains the key attributes below.

Field Type Description
farms String[] Farms list where the blacklist is applied.
name String Blacklist name. It is used as a 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 the system administrator.
status String The possible values are: up, the blacklist is activated 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 the 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://<zevenet_server>:444/zapi/v4.0/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 blacklist is applied.
name String Blacklist name. It is used as a 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 administrator.
status String The possible values are: up, the blacklist is activated 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 system and maintained by the 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 blacklist is applied.
name String Blacklist name. It is used as a 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 administrator.
type String Where the list is saved and who maintains it. The values are: local, the list is saved in the system and maintained by the system administrator; or remote, the list is downloaded from a remote url.
sources Object[] Source 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/bitmask 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 an 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 frequency value is weekly or monthly. If frequency is weekly this parameter must be a day 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 depends on the fields frequency.
status String The possible values are: up, the blacklist is activated 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.
units String Period unit. The options are: minutes, indicate the list will be updated every configured minutes; or hours, the 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://<zevenet_server>:444/zapi/v4.0/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://<zevenet_server>:444/zapi/v4.0/zapi.cgi/ipds/blacklists

POST /ipds/blacklists

Create a blacklist to be used in the farms. Blacklists can be of two types:

  1. Local: The sources are added by the user. The list is saved locally.
  2. 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 a 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 service 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. The default value is denied.
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 the 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 the next key attributes.

Field Type Description
farms String[] Farms list where the blacklist is applied.
name String Blacklist name. It is used as a 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 the 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 service 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://<zevenet_server>:444/zapi/v4.0/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 a unique identifier. Only it is modifiable 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. To change only a source please see documentation section IPDS > Blacklists > Modify a source of a blacklist. Sources only are modifiable 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 the 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://<zevenet_server>:444/zapi/v4.0/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://<zevenet_server>:444/zapi/v4.0/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://<zevenet_server>:444/zapi/v4.0/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://<zevenet_server>:444/zapi/v4.0/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://<zevenet_server>:444/zapi/v4.0/zapi.cgi/ipds/blacklists/newListRem

Request parameters for a remote list

Field Type Description
farms String[] Farms list where the blacklist is applied.
name String Blacklist name. It is used as a 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 period, 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 an 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 weekday (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 depends on the fields frequency.

Time period object

These are the fields when a period 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 an 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 weekday 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 the 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://<zevenet_server>:444/zapi/v4.0/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 of sources of a blacklist

List source from a blacklist

Request example:

curl -k -X DELETE -H "ZAPI_KEY: <ZAPI_KEY_STRING>"
https://<zevenet_server>:444/zapi/v4.0/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://<zevenet_server>:444/zapi/v4.0/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 network 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 the 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://<zevenet_server>:444/zapi/v4.0/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 network 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 the 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://<zevenet_server>:444/zapi/v4.0/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 action

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://<zevenet_server>:444/zapi/v4.0/zapi.cgi/ipds/blacklists/remoteList/actions

POST /ipds/blacklists/<name>/actions

Apply an 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 blacklist 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 updates 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 the 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 set connection limits for sources or incoming throughtput in order to ensure the service is available and it is not overloaded. It can enforcement the TCP protocol, checking the traffic is coherent and it is not bogus. Before applying a rule to a farm, create an object with the configuration wished. Next, applied it to all the farms that you need it.

It is necessary to create an object before to apply a rule to a farm.

limitsec

Limit of new connection per second and source. Only available in farms working with TCP protocol.

Field Type Description
name String It is the object rule unique identifier.
limit Number It is the maximum 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 working with TCP protocol.

Field Type Description
name String It is the object rule unique identifier.
limit_conns Number It is the maximum number of current connection from a source.

bogustcpflags

Check TCP protocol is respected. This rule has not got configuration parameters so creating only an object you will be able to use in all farms. Only available in farms working 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 working with TCP protocol.

Field Type Description
name String It is the object rule unique identifier.
limit Number It is the maximum number of reset requests 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.

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://<zevenet_server>:444/zapi/v4.0/zapi.cgi/ipds/dos/rules

GET /ipds/dos/rules

Show a list of DoS rules.

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://<zevenet_server>:444/zapi/v4.0/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 of 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 activated and filtering traffic; or down, the rule is not running and it is not filtering traffic.

Additionally, depending on 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 maximum 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 maximum number of current connections 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 maximum number of reset requests 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.

Retrieve a DoS rule

Retrieve a DoS rule

Request example for farm rule:

curl -k -X GET -H "ZAPI_KEY: <ZAPI_KEY_STRING>"
https://<zevenet_server>:444/zapi/v4.0/zapi.cgi/ipds/dos/limitConnHttp

Request example for system rule:

curl -k -X GET -H "ZAPI_KEY: <ZAPI_KEY_STRING>"
https://<zevenet_server>:444/zapi/v4.0/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 of 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 activated and filtering traffic; or down, the rule is not running and it is not filtering traffic.

Additionally, depend on 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 maximum 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 maximum number of current connection sfrom 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 maximum number of reset requests 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.

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://<zevenet_server>:444/zapi/v4.0/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 the 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://<zevenet_server>:444/zapi/v4.0/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 maximum 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 maximum number of current connections from a source.

bogustcpflags

No have parameters.

limitrst

Field Type Description
limit Number It is the maximum number of reset requests 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.

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 the 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://<zevenet_server>:444/zapi/v4.0/zapi.cgi/ipds/dos/limitConnHttp

DELETE /ipds/dos/<name>

name is the DoS rule unique identifier.

Response example:

{
   "description" : "Delete DoS rule",
   "message" : "Deleted limitConnHttp successful.",
   "success" : "true"
}

Apply an action to a DoS rule

Apply an action

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://<zevenet_server>:444/zapi/v4.0/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 disables the DoS for all farms where the DoS rule is applied, the traffic won’t be blocked or allowed. 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 let create a security system delegating, the tedious task of maintaining an updated security system, to a specialist. RBL checks load balancer input traffic in an extern database through the DNS protocol. The DNS server owner is the responsibility of updating and providing a quality source. 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 provider list that sorts the source for different criteria, as the type of the attack or severity of an attack.

Once the DNS domains have been created, it is necessary to create an 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://<zevenet_server>:444/zapi/v4.0/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 contains the key attributes below.

Field Type Description
cache_size Number It is the number of IP sources 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 of all the domains that the rule is querying.
farms String[] Farms list where the blacklist 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 a unique identifier.
only_logging String If the value is true, when an IP matches in a domain, it will be logged; or if this field has the value false, when an IP matches in a domain, the IP will be logged and the packet will be dropped.
queue_size Number It is the number of packets 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 is the number of packets 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 an RBL rule

Retrieve RBL rule

Request example:

curl -k -X GET -H "ZAPI_KEY: <ZAPI_KEY_STRING>"
https://<zevenet_server>:444/zapi/v4.0/zapi.cgi/ipds/rbl/protection_ssh

GET /ipds/rbl/<name>

Show the RBL configuration and its description parameters. name is used as 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 sources 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 of all the domains that the rule is querying.
farms String[] Farms list where the blacklist 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 a unique identifier.
only_logging String If the value is true, when an IP matches in a domain, it will be logged; or if this field has the value false, when an IP matches in a domain, the IP will be logged and the packet will be dropped.
queue_size Number It is the number of packets 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 is the number of packets 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 an 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://<zevenet_server>:444/zapi/v4.0/zapi.cgi/ipds/rbl

POST /ipds/rbl

Create an RBL rule to be used on farms.

Request parameters

Field Type Description Required
name String RBL rule name. It is used as a unique identifier. true

Response example:

{
   "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 the next key attributes.

Field Type Description
cache_size Number It is the number of IP sources 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 of all the domains that the rule is querying.
farms String[] Farms list where the blacklist 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 a unique identifier.
only_logging String If the value is true, when an IP matches in a domain, it will be logged; or if this field has the value false, when an IP matches in a domain, the IP will be logged and the packet will be dropped.
queue_size Number It is the number of packets 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 is the number of packets 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 an 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://<zevenet_server>:444/zapi/v4.0/zapi.cgi/ipds/rbl/all

PUT /ipds/rbl/<name>

Modify the configuration of an RBL rule. name is the RBL rules unique identifier.

Request parameters:

Field Type Description
cache_size Number It is the number of IP sources 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 a unique identifier.
only_logging String If the value is true, when an IP matches in a domain, it will be logged; or if this field has the value false, when an IP matches in a domain, the IP will be logged and the packet will be dropped.
queue_size Number It is the number of packets that the rule can keep in the queue.
threadmax String It is the number of packets 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 the next key attributes.

Field Type Description
cache_size Number It is the number of IP sources 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 of all the domains that the rule is querying.
farms String[] Farms list where the blacklist 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 a unique identifier.
only_logging String If the value is true, when an IP matches in a domain, it will be logged; or if this field has the value false, when an IP matches in a domain, the IP will be logged and the packet will be dropped.
queue_size Number It is the number of packets 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 is the number of packets 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 an 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://<zevenet_server>:444/zapi/v4.0/zapi.cgi/ipds/rbl/all_reported

POST /ipds/rbl/<name>

Copy an RBL rule to create a new rule. name is the RBL rules unique identifier.

Request parameters:

Field Type Description required
name String RBL rule name for the new rule. It is used as a 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 the next key attributes.

Field Type Description
cache_size Number It is the number of IP sources 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 of all the domains that the rule is querying.
farms String[] Farms list where the blacklist 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 a unique identifier.
only_logging String If the value is true, when an IP matches in a domain, it will be logged; or if this field has the value false, when an IP matches in a domain, the IP will be logged and the packet will be dropped.
queue_size Number It is the number of packets 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 is the number of packets 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 an RBL rule

Delete a RBL

Request example:

curl -k -X DELETE -H "ZAPI_KEY: <ZAPI_KEY_STRING>"
https://<zevenet_server>:444/zapi/v4.0/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://<zevenet_server>:444/zapi/v4.0/zapi.cgi/ipds/rbl/domains

GET /ipds/rbl/domains

List all available 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 types of domains list as the 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 identifies 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://<zevenet_server>:444/zapi/v4.0/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 an RBL provider where an 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 the 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://<zevenet_server>:444/zapi/v4.0/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 the load balancer administrator.

User domain object:

Field Type Description
id Number[] It is the id that identifies 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://<zevenet_server>:444/zapi/v4.0/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"
}

Add a domain to a RBL rule

Add a domain to a RBL rule

Request example:

curl -k -X POST -H "ZAPI_KEY: <ZAPI_KEY_STRING>" -H 'Content-Type: application/json'
-d '{"domain":"apache.rbl.zevenet.com"}'
https://<zevenet_server>:444/zapi/v4.0/zapi.cgi/ipds/rbl/tstrule/domains

POST /ipds/rbl/<name>/domains

Add a domain that was added previously to the load balancer to an RBL rule.

The URI parameter name is the RBL rule unique identifier.

Request parameters

Field Type Description Required
domain String It is a zone of an RBL provider where an RBL rule will do queries. true

Response example:

{
   "description" : "Add the domain 'apache.rbl.zevenet.com' to the RBL rule tstrule",
   "message" : "Added apache.rbl.zevenet.com domain successfully.",
   "params" : {
      "cache_size" : 8192,
      "cache_time" : 3600,
      "domains" : [
         {
            "domain" : "apache.rbl.zevenet.com"
         }
      ],
      "farms" : [],
      "local_traffic" : "false",
      "log_level" : 5,
      "name" : "tstrule",
      "only_logging" : "false",
      "queue_size" : 64538,
      "status" : "down",
      "threadmax" : 0
   }
}

Response parameters

The response will be a JSON with the parameters of the RBL rule updated.

Field Type Description
cache_size Number It is the number of IP sources 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 of all the domains that the rule is querying.
farms String[] Farms list where the blacklist 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 a unique identifier.
only_logging String If the value is true, when an IP matches in a domain, it will be logged; or if this field has the value false, when an IP matches in a domain, the IP will be logged and the packet will be dropped.
queue_size Number It is the number of packets 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 is the number of packets 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 domain from an RBL rule

Delete a domain from a RBL rule

Request example:

curl -k -X DELETE -H "ZAPI_KEY: <ZAPI_KEY_STRING>"
https://<zevenet_server>:444/zapi/v4.0/zapi.cgi/ipds/rbl/tstrule/domains/apache.rbl.zevenet.com

DELETE /ipds/rbl/<name>/domains/<domain>

Delete a domain from an RBL rule.

The URI parameter name is RBL unique identifier. The URI parameter domain is one of the domain strings listed in the domains response fields of an RBL rule.

Response example:

{
   "description" : "Delete the domain apache.rbl.zevenet.com from a RBL rule tstrule",
   "message" : "The domain apache.rbl.zevenet.com has been deleted successful from the RBL rule tstrule.",
   "success" : "true"
}

Apply an action in an 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/v4.0/zapi.cgi/ipds/rbl/<name>/action

POST /ipds/rbl/<id>/farms/<farmname>/actions

Apply an action to an 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.

id is the domain user identifier that it will be deleted. name is the RBL rules 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.

IPDS - WAF

The Web Application Firewall, WAF, is the dedicated tool to detect and to block malicious HTTP traffic that is going through the HTTP(s) farms. WAF works searching and analyzing patterns with the purpose of applying advanced security policies.

Zevenet WAF builds and manages rules with format SecLang (called custom in the creation, and are showed in the raw field). This formatting language is used by the libmodsecurity library, to create rule sets to link them with farms of type HTTP. Also, it is possible to configure WAF rules without the necessity of knowing the SecLang syntax, only using the parameters expected by the ZAPI. The API will build unconditionally actions that will execute sentences while the management of the incoming HTTP request. Also, the action can be triggered using match conditions to execute it when it is required

A ruleset is a set of rules with a general configuration. It is important to know that the sets are sequential, so the order of the rules will be respect. If a rule with a BLOCK resolution matches the request will be denied. The same way, if a rule with an ALLOW resolution matches, no more rules will be checked and the request is accepted.

Because the order of the rules is important, there are available options to jump rules, as the skip parameter or the rules of type marker to set points where to jump.

Once the rulesets have been configured, it is the moment to apply them to the HTTP farms. A farm accepts as many rule sets as the security administrator needed. In the ruleset context the order it is important too, so the sets must be sorted.

Definition of the WAF objects:

Ruleset object:

A set object has two keys:

The key configuration is the global behavior of the set. It establishes the default behavior for the rules.

Configuration

Field Type Description
disable_rules Number[] It is a list of rules of the set to disable. The expected value is the rule_id of the rule is going to be disabled.
process_request_body String This parameter enables the check of the request body HTTP. The possible values are true to enable the check; or false to disable the check.
process_response_body String This parameter enables the check of the response body HTTP. The possible values are true to enable the check; or false to disable the check.
request_body_limit Number Set a limit to the HTTP request body. This number is the size in Bytes. If the body size is greater than the limit, it will be skipped.
default_action String It is the default value to the rule parameter resolution rule parameter. This action will be executed in the case that a rule matches and the only_logging parameter is not enabled. The possible values are: pass, the rule will apply the other options configured (log, execute…) and the request won’t be cut. The following rules will be checked; deny, ends the connection, the following rules won’t be executed; redirect, the client will be redirected to the URL configured in the parameter redirect_url.
status String It shows the status of the set rule. The possible returned values are down, the set rule is disabled; or up, the set rule is enabled, it works blocking or allowing according to the resolution parameter.
only_logging String If this parameter is enabled, the resolution will never be executed, not cutting the connection in any case. The possible values are: true for enabling the only logging working mode; or false, WAF will cut the connection if a resolution (deny or redirect) is executed.
audit String If this parameter is enabled, WAF report an extended log file with the result of each HTTP request analysis. The possible values are: true, enables the audit log; or false, disables the audit logging.
default_log String It is the default value to the log rule parameter. If its value is set to true all rule matches will be logged. If its value is set to false the matches will not be logged.
default_phase String It is the default value to the phase rule parameter. The phase represents the point of the HTTP request where a rule will be executed. The possible values are 1, it is executed when the request headers are received; 2, it is executed when the body request is received; 3, it is executed when the response headers are received; 4, it is executed when the response body is received; or 5, it is executed just before logging.

Rules

The key rules is a list of rules and each element is a rule object.

Rule

A rule can have one of the following types:

Action

When the rule is executed, it will execute actions that there are defined.

To manage if a rule will be executed or not depend on the incoming request, it is used the parameter match. If the parameter match is not set, the rule will be executed unconditionally, this option is commonly used to initialize variables or to set default actions.

The parameters of an action rule can be divided into several topics:

Field Type Description
raw String This field contains a string with the rule in SecLang syntax.
id Number It is the unique identifier for a rule inside of the ruleset. It is used to edit and to move the rule.
rule_id Number It is the rule identifier. It must be unique in the system. It is used to copy a rule. This parameter is only to rules of type action. If two rulesets contain a rule with the same rule_id won’t be able to link with the same farm.
type String It shows the type of rule. The possible values are: action, marker or custom.
resolution String To execute this action, it is necessary to have configured the ruleset parameter status to true. This parameter is the action to apply when a WAF rule matches. The possible values are: pass, the rule will apply the other options configured (log, execute…) and the request won’t be cut. The following rules will be checked; deny, ends the connection, the following rules won’t be executed; redirect, the client will be redirected to the URL configured in the parameter redirect_url; default_action, the rule will execute the action that was set in the ruleset parameter default_action.
audit String This parameter overwritten the audit set rule parameter for the current rule in the case the rule matches. If it has the value true, the rule will always report in the audit log; If it has the value false, in the case that a match, the rule will never report to the audit log; if the default behavior is desired, set as blank string.
matches Match Object[] It is a list of matches object. The rule will be executed in the case that all objects will match.
description String It is a descriptive message for the rule.
execute String It is the path to an LUA script. This script will be executed when the rule matches. The script must exist before configuring this parameter.
log String If this parameter has the value true, the rule will log in a successful match. To not log, the parameter has to be set with the value false. If the value is set to blank the ruleset parameter default_log will be executed.
log_data String This parameter allows logging additional information. It can be used with variables to log any interesting transaction information.
phase String The phase represents the point of the HTTP request where a rule will be executed. The possible values are 1, it is executed when the request headers are received; 2, it is executed when the body request is received; 3, it is executed when the response headers are received; 4, it is executed when the response body is received; or 5, it is executed just before logging.
redirect_url String It is the URL where redirecting the client in the case that the resolution redirect is executed. This parameter can be set only when the rule resolution has the value redirect.
skip Number It is the number of rules to skip when the rule matches. The skipped rules are in the same phase.
skip_after String This parameter has two possible kinds of values: a rule_id, in a successful match, WAF jump to the rule_id selected; or a “string”, the string must be an existing mark, all rules will skip until reaching the mark. The skip_after parameter works only over rules in the same phase.
tag String[] The tags are marks to classify the matched traffic.
modified String It indicates if the rule has been edited by the user. In another case, the rule was been uploaded by the zevenet-ipds package.

Match

The match object builds a match condition. If this is a success, the rule will be executed. To evaluate the match, the WAF will execute an operation (parameters operator and operating) against a variables list. If it exists some match of the operation with some of the variables of the list, the match is taken as a success. For example, to look for a regexp in the request headers and the hostname, it can be evaluated with the following configuration.

{ “variables” : [ “REQUEST_HEADERS”, “SERVER_NAME” ], “operator” : “strRegexp”, “operating” : “localhost” }

Field Type Description
match_index Number It is the index of the match object. It is used as the unique identifier inside of the match list of the rule.
not_match String It is used to indicate that the rule should not match with the condition.
capture String This parameter enables the feature of capturing the value obtained from a regular expression. To use this parameter with sense, it has to be used with the operator strRegexp. The possible values are true or false.
multi_match String This parameter is used when more than one transformations are configured. The rule will try a match of the variables, the operator and the operating for each value of transformations. The possible values are: true, enables multi match; or false, disables the multi match feature.
transformations String[] The transformation modifies the variables before than apply them to the operator and operating. Here, there is list of the transformation. This parameter is useful to remove anti-avoid techniques or to remove codification data.
variables String[] It is against which part of the HTTP transaction the rule will try the match. The possible values are in this table.
operator String It is how the rule tries the match. This parameter is used combined with operating. The type of value expected depend on the operator table.
operating String It is what the rules try in the match. The parameter is used combined with operator.

Mark

Marks are useful to modify the flow of the rules, and limiting the different sets. They are used by the parameter skip_after of the rules action.

Field Type Description
raw String This field contains the rule in SecLang syntax.
id Number It is the unique identifier inside of the ruleset. It is used to modify and to move the rule.
type String It shows the type of rule, action, marker or custom.
mark String It is a name for the mark.

Custom

If the before ways of creating a rule is not enough for the load balancer administrator and they are with the SecLang syntax, it is possible to create rules or batch of rules through the custom option. This field accepts any directive if the directive and parameter are supported by the SecLang syntax.

Field Type Description
raw String This field contains the rule in SecLang syntax.
id Number It is the unique identifier inside of the ruleset. It is used to modify and to move the rule.
type String It shows the type of rule, action, marker or custom.

List of data for building matches

Operators

Operator Description
strBegins The rule will match if any of the variables begins with the value of operating.
strContains The rule will match if any of the variables contains the value of operating.
strContainsWord The rule will match if any of the variables contains the word of the value of operating.
strEnds The rule will match if any of the variables ends with the value of operating.
strWithin The rule will match if any of the variables begins with the value of operating.
strMatch The rule will match if any of the variables matches with the value of operating. This operating can be a list of strings split by the character **
strEq The rule will match if any of the variables is identical to the value of operating.
strRegex The rule will match if any of the variables matches in the regular expression used in operating.
strPhrases The rule will match if any of the variables matches in any of the values of the list operating.
strPhrasesFromFile It the same that the operator strPhrases but the operating is a file where it is defined as a list of phrases.
intEQ The rule will match if any of the variables is equal to the number used in operating.
intGE The rule will match if any of the variables is greater or equal to the number used in operating.
intGT The rule will match if any of the variables is greater than the number used in operating.
intLE The rule will match if any of the variables is lower or equal to the number used in operating.
intLT The rule will match if any of the variables is lower than the number used in operating.
detectSQLi It applies the detection of SQL injection to the list of variables. This operator does not expect any operating.
detectXSS It applies the detection of XSS injection to the list of variables. This operator does not expect any operating.
ipMatch Try to match the IP or network segments of operating with the list of variables.
ipMatchFromFile It is the same as the operator ipMatch, but this try the match of the variables against a file with a list of IPs and network segments.
validateByteRange It checks that the number of the byte of the variables are in one of the operating values. An example for operating is “10, 13, 32-126”.
validateUrlEncoding It validates encoded data. This operator must be used only for data that does not encode data commonly or for data are encoded several times.
validateUtf8Encoding It validate that variables are UTF-8. This operator does not expect any operating.
verifyCreditCard It verifies if variables are a credit card number. This parameter accepts a regular expression as operating, if it matches then it applies the credit card verification.
verifySSN It verifies if variables are a US Social Security Number. This parameter accepts a regular expression as operating, if it matches then it applies the SSN verify.
matchAllways It returns true always, forcing a match.
matchNever It returns false always, forcing a non-match.

Transformations

The transformations are applied to the variables before checking the operator.

The transformations are applied in the same order as they appear.

The available transactions are:

base64Decode, sqlHexDecode, base64DecodeExt, base64Encode, cmdLine, compressWhitespace, cssDecode, escapeSeqDecode, hexDecode, hexEncode, htmlEntityDecode, jsDecode, length, lowercase, md5, none, normalisePath, normalizePath, normalisePathWin, normalizePathWin, parityEven7bit, parityOdd7bit, parityZero7bit, removeNulls, removeWhitespace, replaceComments, removeCommentsChar, removeComments, replaceNulls, urlDecode, uppercase, urlDecodeUni, urlEncode, utf8toUnicode, sha1, trimLeft, trimRight and trim

Variables

A variable can save a set of variables related, for example, ARGS can be expanded and getting a specific variable. It is possible to use, for example, ARGS:parameter, to expand de variable ARGS and get the value of the parameter that is the ARGS set.

Using the operator & with a variable, the variable will return the number of parameters that have saved.

Using the operator !, this variable is excluded for the match.

Variables Description
ARGS It is a collection with the values of arguments in a request.
ARGS_JSON It is a collection with the values of arguments in a JSON request. This variable will be available in the case that WAF parses the JSON arguments, for it, the rule set REQUEST-901-INITIALIZATION should be enabled.
ARGS_COMBINED_SIZE total size of the request parameters. The files are excluded.
ARGS_NAMES It is a collection with the names of the arguments in a request.
FILES It contains the file names in the user file system. Only when the data is multipart/form-data.
FILES_COMBINED_SIZE It is the total size of the files in a request. Only when the data is multipart/form-data.
FILES_NAMES It is a list of filenames used to upload the files. Only when the data is multipart/form-data.
FILES_SIZES It contains a list of individual file sizes. Only when the data is multipart/form-data.
REQBODY_ERROR This variable is 1 if the request body format is not correct for a JSON or XML, else it has the value 0.
REQUEST_BODY It is the raw body request. If the request has not the “application/x-www-form-urlencoded” header, it is necessary to use “ctl:forceRequestBodyVariable” in the REQUEST_HEADER phase.
REQUEST_BODY_LENGTH It is the number of bytes of the request body.
REQUEST_COOKIES It is a list of all request cookies values.
REQUEST_COOKIES_NAMES It is a list with all request cookies names.
REQUEST_HEADERS This variable has all the request headers.
REQUEST_HEADERS_NAMES This variable has a list with the request headers names.
REQUEST_METHOD It is the request method.
REQUEST_PROTOCOL This variable holds the request HTTP version protocol.
REQUEST_URI It is the URI request path. The virtual host is excluded.
PATH_INFO It is the information before the URI path.
FULL_REQUEST It is the full request.
FULL_REQUEST_LENGTH It is the number of bytes that full request can have.
RESPONSE_BODY It is the raw body response.
RESPONSE_CONTENT_LENGTH It is the number of bytes of the response body.
RESPONSE_HEADERS This variable has all response headers.
RESPONSE_HEADERS_NAMES This variable has a list with the response headers names.
RESPONSE_PROTOCOL This variable holds the response HTTP version protocol.
RESPONSE_STATUS It is the response HTTP code.
REMOTE_ADDR It is the IP address of the client.
REMOTE_PORT It is the port where the client initializes the connection.
REMOTE_USER It is the name of the authenticated user.
TIME It is the server time. The format is hours:minutes:seconds.
DURATION It is the number of milliseconds since the beginning of the current transaction.
MULTIPART_FILENAME It is the field filename in a multipart request.
MULTIPART_NAME It is the field name in a multipart request.
MATCHED_VAR It is the matched value in the last match operation. This value does not need the capture option but it is replaced in each match operation.
MATCHED_VARS It is a list of all matched values.
SERVER_ADDR It is the IP address of the server.
SERVER_NAME It is the virtual host, it gets from the request URI.
ENV It is the environment variables of the WAF.
TX It is a collection of variables for the current transaction. These variables will be removed when the transaction ends. The variables TX:0-TX:9 saves the values captured with the strRegex or strPhrases operators.

List the WAF rule sets

List the WAF rule sets

Request example:

curl -k -X GET -H "ZAPI_KEY: <ZAPI_KEY_STRING>"
https://<zevenet_server>:444/zapi/v4.0/zapi.cgi/ipds/waf

GET /ipds/waf

Get the list of WAF rulesets of the load balancer.

Response example:

{
          "params" : [
                        {
                          "farms" : [],
                          "status" : "down",
                          "name" : "REQUEST-901-INITIALIZATION"
                        },
                        {
                          "name" : "REQUEST-903-9001-DRUPAL-EXCLUSION-RULES",
                          "status" : "down",
                          "farms" : []
                        },
                        {
                          "status" : "down",
                          "name" : "REQUEST-903-9002-WORDPRESS-EXCLUSION-RULES",
                          "farms" : []
                        },
                        {
                          "name" : "REQUEST-903-9003-NEXTCLOUD-EXCLUSION-RULES",
                          "status" : "down",
                          "farms" : []
                        }
                      ],
          "description" : "List the WAF sets"
}

Response parameters

Field Type Description
name String It is the ruleset name, it is used as the unique rule set identifier.
status String It shows the status of the set rule. The possible returned values are down, the set rule is disabled; or up, the set rule is enabled, it works blocking or allowing according to the resolution parameter.
farms String[] It is a list of farm names. Those are all farms linked with the ruleset.

Retrieve a WAF ruleset

Retrieve WAF rule set

Request example:

curl -k -X GET -H "ZAPI_KEY: <ZAPI_KEY_STRING>"
https://<zevenet_server>:444/zapi/v4.0/zapi.cgi/ipds/waf/test_waf_ori

GET /ipds/waf/<name>

Show the WAF configuration and its rules.

The name URI parameter is the WAF rule unique identifier.

Response example:

{
          "params" : {
                        "rules" : [
                                     {
                                       "audit" : "",
                                       "id" : "0",
                                       "log" : "",
                                       "modified" : "yes",
                                       "resolution" : "pass",
                                       "description" : "The ID is 0",
                                       "phase" : 1,
                                       "raw" : "SecRule TX:sampling_rnd100 \"@rx ^0([0-9])\" \"id:1003,phase:1,pass\"",
                                       "tag" : [],
                                       "rule_id" : "1003",
                                       "execute" : "",
                                       "matches" : [
                                                      {
                                                        "transformations" : [],
                                                        "capture" : "false",
                                                        "match_index" : 0,
                                                        "multi_match" : "false",
                                                        "not_match" : "false",
                                                        "operator" : "strRegex",
                                                        "operating" : "^0([0-9])",
                                                        "variables" : [
                                                                         "TX:sampling_rnd100"
                                                                       ]
                                                      }
                                                    ],
                                       "redirect_url" : "",
                                       "skip" : 0,
                                       "type" : "action",
                                       "skip_after" : ""
                                     },
                                     {
                                       "skip_after" : "",
                                       "type" : "action",
                                       "skip" : 0,
                                       "redirect_url" : "",
                                       "matches" : [
                                                      {
                                                        "transformations" : [
                                                                               "none"
                                                                             ],
                                                        "capture" : "false",
                                                        "match_index" : 0,
                                                        "multi_match" : "false",
                                                        "not_match" : "false",
                                                        "operating" : "GET",
                                                        "operator" : "strEq",
                                                        "variables" : [
                                                                         "REQUEST_METHOD"
                                                                       ]
                                                      }
                                                    ],
                                       "execute" : "",
                                       "rule_id" : "9001185",
                                       "tag" : [],
                                       "raw" : "SecRule REQUEST_METHOD \"@streq GET\" \"id:9001185,phase:1,t:none,pass,nolog,noauditlog\"",
                                       "phase" : 1,
                                       "description" : "The ID is 1",
                                       "resolution" : "pass",
                                       "modified" : "yes",
                                       "id" : "1",
                                       "log" : "false",
                                       "audit" : "false"
                                     },
                                     {
                                       "skip_after" : "12",
                                       "type" : "action",
                                       "skip" : "1",
                                       "redirect_url" : "",
                                       "matches" : [],
                                       "execute" : "",
                                       "rule_id" : "200",
                                       "raw" : "SecAction \"\\
    id:200,\\
    msg:\'Rule to modify the another one\',\\
    tag:testing 2,\\
    tag:Api tests 2,\\
    phase:4,\\
    deny,\\
    noauditlog,\\
    skip:1,\\
    skipAfter:12\"",
                                       "tag" : [
                                                  "testing 2",
                                                  "Api tests 2"
                                                ],
                                       "phase" : 4,
                                       "description" : "Rule to modify the another one",
                                       "resolution" : "deny",
                                       "modified" : "yes",
                                       "id" : 2,
                                       "log" : "",
                                       "audit" : "false"
                                     },
                                     {
                                       "type" : "action",
                                       "skip_after" : "",
                                       "matches" : [
                                                      {
                                                        "not_match" : "false",
                                                        "multi_match" : "false",
                                                        "operator" : "strRegex",
                                                        "operating" : "@ ",
                                                        "variables" : [
                                                                         "REQUEST_COOKIES:/S?SESS[a-f0-9]+/"
                                                                       ],
                                                        "transformations" : [],
                                                        "capture" : "false",
                                                        "match_index" : 0
                                                      }
                                                    ],
                                       "redirect_url" : "",
                                       "skip" : 0,
                                       "rule_id" : "9001187",
                                       "execute" : "",
                                       "raw" : "SecRule REQUEST_COOKIES:/S?SESS[a-f0-9]+/ \"@ \" \"id:9001187,ctl:requestBodyAccess=Off\"",
                                       "tag" : [],
                                       "phase" : "",
                                       "modified" : "yes",
                                       "resolution" : "",
                                       "description" : "The ID is 3",
                                       "audit" : "",
                                       "id" : "3",
                                       "log" : ""
                                     }
                                   ],
                        "farms" : [],
                        "configuration" : {
                                             "audit" : "false",
                                             "process_request_body" : "false",
                                             "default_action" : "pass",
                                             "default_log" : "true",
                                             "disable_rules" : [],
                                             "only_logging" : "false",
                                             "default_phase" : 2,
                                             "request_body_limit" : 0,
                                             "process_response_body" : "false",
                                             "status" : "down"
                                           }
                      },
          "description" : "Get the WAF set test_waf_ori"
}

Response parameters

The response will be a JSON object with a key set to params. The params object contains three keys: One key contains the rule set configuration, configuration. Another key is set as rules, this contains the list of rules of the set. Rules. The last one is farms, this is the farm list linked with the ruleset.

Create a WAF ruleset

Create a WAF rule set

Request example:

curl -k -X POST -H "ZAPI_KEY: <ZAPI_KEY_STRING>" -H 'Content-Type: application/json'
-d '{"name":"CUSTOM-RULESET"}'
https://<zevenet_server>:444/zapi/v4.0/zapi.cgi/ipds/waf

POST /ipds/waf

Create a WAF ruleset to be used to farms. It is created empty without any rule and all it is disabled by default

Request parameters

Field Type Description Required
name String WAF ruleset name. It is used as the unique identifier. true
copy_from String It is a WAF ruleset name, if this parameter is sent the new set will be a copy from this.

Response example:

{
   "description" : "Create the WAF set, CUSTOM-RULESET",
   "message" : "Added the WAF set CUSTOM-RULESET",
   "params" : {
      "configuration" : {
         "audit" : "false",
         "default_action" : "allow",
         "default_log" : "",
         "default_phase" : "1",
         "disable_rules" : [],
         "process_request_body" : "false",
         "process_response_body" : "false",
         "request_body_limit" : "",
         "status" : "false"
      },
      "rules" : []
   }
}

Response parameters

The response will be a JSON object with a key set to params. The param key has two elements:

A configuration object:

Field Type Description
disable_rules Number[] It is a list of rule_id. All of them will be disabled.
process_request_body String This parameter enables the checking of the request body HTTP. The possible values are true to enable the check; or false to disable the check.
process_response_body String This parameter enables the checking of the response body HTTP. The possible values are true to enable the check; or false to disable the check.
request_body_limit Number Set a limit to the HTTP request body. This number is the size in Bytes.
status String It sets how the set rule will work. The possible values are false, disables the set; detection, the set does not apply the action set in the parameter action; or true, the set will work blocking or allowing according to the action parameter.
audit String The possible values are: true, enables the audit; or false, disables the audit logging.
default_action String It is the default value to the action rule parameter. The possible values are: pass, the rule will apply the other options configured and the request won’t be cut; deny, ends the connection, the rest of rules won’t be executed; redirect:, the client will be redirected to the set URL; block, the rule will execute the action that was set in the configuration set default_action. To enable this action, it is necessary to have set parameter status to on.
default_log String It is the default value to the log rule parameter. If its value is set to true all matches will be logged. If its value is set to false the matches will no be logged.
default_phase String It is the default value to the phase rule parameter. The phase represents the point of the HTTP request where a rule will be executed. The possible values are 1, it is executed when the request headers are received; 2, it is executed when the body request is received; 3, it is executed when the response headers are received; 4, it is executed when the response body is received; or 5, it is executed just before logging.

A list of rules objects:

This list is empty when the ruleset is created.

Modify the configuration of WAF ruleset

Modify the configuration of WAF rule set

Request example:

curl -k -X PUT -H 'Content-Type: application/json' -H "ZAPI_KEY: <ZAPI_KEY_STRING>"
-d '{"audit":"true","disable_rules":[100],"process_request_body":"true","status":"detection",
"request_body_limit":6456456,"process_response_body":"true","only_logging":"false"}'
https://<zevenet_server>:444/zapi/v4.0/zapi.cgi/ipds/waf/CUSTOM-RULESET

PUT /ipds/waf/<name>

Modify the global setting of a WAF ruleset. The name is the WAF ruleset unique identifier.

Request parameters:

Field Type Description
disable_rules Number[] It is a list of rule_id. All of them will be disabled.
process_request_body String This parameter enables the checking of the request body HTTP. The possible values are true to enable the check; or false to disable the check.
process_response_body String This parameter enables the checking of the response body HTTP. The possible values are true to enable the check; or false to disable the check.
request_body_limit Number Set a limit to the HTTP request body. This number is the size in Bytes.
audit String The possible values are: true, enables the audit; or false, disables the audit logging.
default_action String It is the default value to the action rule parameter. The possible values are: pass, the rule will apply the other options configured and the request won’t be cut; deny, ends the connection, the rest of rules won’t be executed; redirect:, the client will be redirected to the set URL; block, the rule will execute the action that was set in the configuration set default_action. To enable this action, it is necessary to have set parameter status to on.
default_log String It is the default value to the log rule parameter. If its value is set to true all matches will be logged. If its value is set to false the matches will no be logged.
default_phase String It is the default value to the phase rule parameter. The phase represents the point of the HTTP request where a rule will be executed. The possible values are 1, it is executed when the request headers are received; 2, it is executed when the body request is received; 3, it is executed when the response headers are received; 4, it is executed when the response body is received; or 5, it is executed just before logging.

Response example:

{
    "configuration" : {
                         "default_phase" : 2,
                         "status" : "down",
                         "process_response_body" : "true",
                         "request_body_limit" : "6456456",
                         "disable_rules" : [
                                              "100"
                                            ],
                         "only_logging" : "false",
                         "default_log" : "true",
                         "default_action" : "pass",
                         "process_request_body" : "true",
                         "audit" : "true"
                       },
    "rules" : []
}

Response parameters

The response will be a JSON object with the set object updated.

Delete a WAF ruleset

Delete a WAF rule set

Request example:

curl -k -X DELETE -H "ZAPI_KEY: <ZAPI_KEY_STRING>"
https://<zevenet_server>:444/zapi/v4.0/zapi.cgi/ipds/waf/test_waf_copied

DELETE /ipds/waf/<name>

Delete a given WAF ruleset. The name is the WAF ruleset unique identifier.

Response example:

{
    "success" : "true",
    "description" : "Delete the WAF set test_waf_copied",
    "message" : "The WAF set test_waf_copied has been deleted successfully."
}

Retrieve a rule of a WAF set

Retrieve a rule of a WAF set

Request example:

curl -k -X GET -H "ZAPI_KEY: <ZAPI_KEY_STRING>"
https://<zevenet_server>:444/zapi/v4.0/zapi.cgi/ipds/waf/test_waf_ori/rules/0

GET /ipds/waf/<name>/rules/<id>

Show the detailed configuration of a WAF rule. The name URI parameter is the WAF set unique identifier. The id URI parameter is the WAF rule unique identifier.

Response example:

{
      "description" : "Get the WAF rule 0 of the set test_waf_ori",
      "params" : {
                    "matches" : [],
                    "redirect_url" : "",
                    "skip" : "2",
                    "type" : "action",
                    "skip_after" : "100",
                    "rule_id" : "199",
                    "execute" : "/opt/example_script.lua",
                    "phase" : 2,
                    "raw" : "SecAction \"\\
    id:199,\\
    msg:\'Testing rule\',\\
    tag:testing,\\
    tag:Api tests,\\
    phase:2,\\
    log,\\
    noauditlog,\\
    skip:2,\\
    skipAfter:100,\\
    exec:/opt/example_script.lua\"",
            "tag" : [
                       "testing",
                       "Api tests"
                     ],
            "audit" : "false",
            "id" : 0,
            "log" : "true",
            "modified" : "yes",
            "description" : "Testing rule",
            "resolution" : ""
        }
}

Response parameters

The response will be a JSON object with a key set to params. The value will be a WAF rule object.

Create a WAF rule

Create a WAF rule

POST /ipds/waf/<name>/rules

There are 3 types of rules available. This call lets to create any of them. Also, it is possible to create rules using the SecLang syntax. They are called custom and are modified by the raw field.

Request example to create a mark rule:

curl -k -X POST -H "ZAPI_KEY: <ZAPI_KEY_STRING>" -H 'Content-Type: application/json'
-d '{"mark":"END-SET1"}'
https://<zevenet_server>:444/zapi/v4.0/zapi.cgi/ipds/waf/CUSTOM-RULESET/rules

Request parameters to create a mark rule

Marks are useful to modify the flow of the rules, and limiting the different sets.

Field Type Description Required
mark String It is a name for the mark. It will be used to use it. true

Request example to create a mark rule:

{
   "description" : "Create a rule in the set CUSTOM-RULESET",
   "message" : "The rule was created properly.",
   "params" : {
      "id" : 0,
      "mark" : "END-SET1",
      "raw" : "SecMarker END-SET1",
      "type" : "marker"
   }
}

Response parameters

The response will be a JSON object with the params key set. The value is a rule object of type marker.

Field Type Description
raw String This field contains the rule in SecLang syntax.
id Number It is the unique identifier inside of the ruleset. It is used to modify and to move the rule.
type String It shows the type of rule, action, marker or custom.
mark String It is a name for the mark. It will be used to use it.

Request example to create an action rule:

curl -k -X POST -H "ZAPI_KEY: <ZAPI_KEY_STRING>" -H 'Content-Type: application/json'
-d '{"skip_after":100,"tag":["testing","Api tests"],"description":"Testing rule","phase":2,"execute":"/opt/example_script.lua","log":"true",
"skip":2,"rule_id":199,"action":"pass","log_data":"match in rule 41","audit":"false"}'
https://<zevenet_server>:444/zapi/v4.0/zapi.cgi/ipds/waf/CUSTOM-RULESET/rules

Request parameters to create an action

The action rules let initialize variables and create default options.

Field Type Description
rule_id Number It is the rule identifier. It must be unique in the system. It is used to copy a rule. This parameter is only to rules of type action. If two rule sets contain a rule with the same rule_id won’t be able to link with the same farm.
resolution String To execute this action, it is necessary to have configured the ruleset parameter status to true. This parameter is the action to apply when a WAF rule matches. The possible values are: pass, the rule will apply the other options configured (log, execute…) and the request won’t be cut. The following rules will be checked; deny, ends the connection, the following rules won’t be executed; redirect, the client will be redirected to the URL configured in the parameter redirect_url; default_action, the rule will execute the action that was set in the ruleset parameter default_action.
audit String This parameter overwritten the audit set rule parameter for the current rule in the case the rule matches. If it has the value true, the rule will always report in the audit log; If it has the value false, in the case that a match, the rule will never report to the audit log; if the default behavior is desired, set as blank string.
description String It is a descriptive message for the rule.
execute String It is the path to an LUA script. This script will be executed when the rule matches. The script must exist before configuring this parameter.
log String If this parameter has the value true, the rule will log in a successful match. To not log, the parameter has to be set with the value false. If the value is set to blank the ruleset parameter default_log will be executed.
log_data String This parameter allows logging additional information. It can be used with variables to log any interesting transaction information.
phase String The phase represents the point of the HTTP request where a rule will be executed. The possible values are 1, it is executed when the request headers are received; 2, it is executed when the body request is received; 3, it is executed when the response headers are received; 4, it is executed when the response body is received; or 5, it is executed just before logging.
redirect_url String It is the URL where redirecting the client in the case that the resolution redirect is executed. This parameter can be set only when the rule resolution has the value redirect.
skip Number It is the number of rules to skip when the rule matches. The skipped rules are in the same phase.
skip_after String This parameter has two possible kinds of values: a rule_id, in a successful match, WAF jumps to the rule_id selected; or a “string”, the string must be an existing mark, all rules will skip until reaching the mark. The skip_after parameter works only over rules in the same phase.
tag String[] The tags are marks to classify the matched traffic.

Response example to create an action:

{
          "description" : "Create a rule in the set test_waf_ori",
          "message" : "The rule was created properly.",
          "params" : {
                        "raw" : "SecAction \"\\
    id:199,\\
    msg:\'Testing rule\',\\
    tag:testing,\\
    tag:Api tests,\\
    phase:2,\\
    log,\\
    noauditlog,\\
    skip:2,\\
    skipAfter:100,\\
    exec:/opt/example_script.lua\"",
                        "tag" : [
                                   "testing",
                                   "Api tests"
                                 ],
                        "phase" : 2,
                        "description" : "Testing rule",
                        "resolution" : "",
                        "modified" : "yes",
                        "log" : "true",
                        "id" : 0,
                        "audit" : "false",
                        "skip_after" : "100",
                        "type" : "action",
                        "skip" : "2",
                        "redirect_url" : "",
                        "matches" : [],
                        "execute" : "/opt/example_script.lua",
                        "rule_id" : "199"
                      }
}

Response parameters

The response will be a JSON object with the params key set. The value is a rule object of type action.

Field Type Description
raw String This field contains a string with the rule in SecLang syntax.
id Number It is the unique identifier for a rule inside of the ruleset. It is used to edit and to move the rule.
rule_id Number It is the rule identifier. It must be unique in the system. It is used to copy a rule. This parameter is only to rules of type action. If two rulesets contain a rule with the same rule_id won’t be able to link with the same farm.
type String It shows the type of rule. The possible values are: action, marker or custom.
resolution String To execute this action, it is necessary to have configured the ruleset parameter status to true. This parameter is the action to apply when a WAF rule matches. The possible values are: pass, the rule will apply the other options configured (log, execute…) and the request won’t be cut. The following rules will be checked; deny, ends the connection, the following rules won’t be executed; redirect, the client will be redirected to the URL configured in the parameter redirect_url; default_action, the rule will execute the action that was set in the ruleset parameter default_action.
audit String This parameter overwritten the audit set rule parameter for the current rule in the case the rule matches. If it has the value true, the rule will always report in the audit log; If it has the value false, in the case that a match, the rule will never report to the audit log; if the default behavior is desired, set as blank string.
matches Match Object[] It is a list of matches object. The rule will be executed in the case that all objects will match.
description String It is a descriptive message for the rule.
execute String It is the path to an LUA script. This script will be executed when the rule matches. The script must exist before configuring this parameter.
log String If this parameter has the value true, the rule will log in a successful match. To not log, the parameter has to be set with the value false. If the value is set to blank the ruleset parameter default_log will be executed.
log_data String This parameter allows logging additional information. It can be used with variables to log any interesting transaction information.
phase String The phase represents the point of the HTTP request where a rule will be executed. The possible values are 1, it is executed when the request headers are received; 2, it is executed when the body request is received; 3, it is executed when the response headers are received; 4, it is executed when the response body is received; or 5, it is executed just before logging.
redirect_url String It is the URL where redirecting the client in the case that the resolution redirect is executed. This parameter can be set only when the rule resolution has the value redirect.
skip Number It is the number of rules to skip when the rule matches. The skipped rules are in the same phase.
skip_after String This parameter has two possible kinds of values: a rule_id, in a successful match, WAF jumps to the rule_id selected; or a “string”, the string must be an existing mark, all rules will skip until reaching the mark. The skip_after parameter works only over rules in the same phase.
tag String[] The tags are marks to classify the matched traffic.
modified String It indicates if the rule has been edited by the user. In another case, the rule was been uploaded by the zevenet-ipds package.

Request example to copy a rule:

curl -k -X POST -H "ZAPI_KEY: <ZAPI_KEY_STRING>" -H 'Content-Type: application/json'
-d '{"copy_from":"12312"}'
https://<zevenet_server>:444/zapi/v4.0/zapi.cgi/ipds/waf/test_waf_ori/rules

Request parameters to copy a rule

Copy a rule through the rule_id. It is possible to copy a rule from another ruleset.

Field Type Description Required
copy_from String It is the WAF rule id, it is showed in the rule_id field of a rule object of type action. true

Response example:

{
    "description" : "Create a rule in the set test_waf_ori",
          "message" : "The rule was created properly.",
          "params" : {
                        "execute" : "/opt/example_script.lua",
                        "rule_id" : "1",
                        "skip" : "2",
                        "matches" : [],
                        "redirect_url" : "",
                        "skip_after" : "100",
                        "type" : "action",
                        "log" : "true",
                        "id" : 2,
                        "audit" : "false",
                        "description" : "Testing rule",
                        "resolution" : "",
                        "modified" : "yes",
                        "phase" : 2,
                        "tag" : [
                                   "testing",
                                   "Api tests"
                                 ],
                        "raw" : "SecAction \"\\
    id:1,\\
    msg:\'Testing rule\',\\
    tag:testing,\\
    tag:Api tests,\\
    phase:2,\\
    log,\\
    noauditlog,\\
    skip:2,\\
    skipAfter:100,\\
    exec:/opt/example_script.lua\""
                      }
}

Response parameters

The response will be a rule object equal to the copied object

Request example to create a custom rule:

curl -k -X POST -H "ZAPI_KEY: <ZAPI_KEY_STRING>" -H 'Content-Type: application/json'
-d '{"raw":"SecRule REQUEST_METHOD \"@streq GET\" \"id:9001185,phase:1,t:none,pass,nolog,noauditlog\"
SecRule REQUEST_COOKIES:/S?SESS[a-f0-9]+/ \"@ \" \"id:9001187,ctl:requestBodyAccess=Off\""}'
https://<zevenet_server>:444/zapi/v4.0/zapi.cgi/ipds/waf/test_waf_ori/rules

Request parameters to create a custom rule

If any of the before ways of creating a rule is not enough for the load balancer administrator and they are familiarized with the SecLang syntax, it is possible to create rules or batch of rules through the custom option. This field accepts any directive if the directive and parameter supported by the SecLang syntax.

Field Type Description Required
raw String It is the WAF rule shows as a string with all its parameters. This field accepts any kind of rule, or batch of rules, that matches with SecLang syntax. true

Response example:

{
          "params" : {
                        "rule_id" : "9001185",
                        "execute" : "",
                        "matches" : [
                                       {
                                         "multi_match" : "false",
                                         "not_match" : "false",
                                         "operating" : "GET",
                                         "operator" : "strEq",
                                         "variables" : [
                                                          "REQUEST_METHOD"
                                                        ],
                                         "transformations" : [
                                                                "none"
                                                              ],
                                         "capture" : "false",
                                         "match_index" : 0
                                       }
                                     ],
                        "redirect_url" : "",
                        "skip" : 0,
                        "type" : "action",
                        "skip_after" : "",
                        "audit" : "false",
                        "log" : "false",
                        "id" : "2",
                        "modified" : "yes",
                        "description" : "The ID is 2",
                        "resolution" : "pass",
                        "phase" : 1,
                        "tag" : [],
                        "raw" : "SecRule REQUEST_METHOD \"@streq GET\" \"id:9001185,phase:1,t:none,pass,nolog,noauditlog\""
                      },
          "description" : "Modify the rule 2 from the set test_waf_ori"
}

Response parameters

The response will be a JSON object with a key set to params. The value is a rule object with the new rule. The type of rule will depend on the type of directive set in the rule.

Modify a WAF rule

Modify a WAF rule

Request example:

curl -k -X PUT -H "ZAPI_KEY: <ZAPI_KEY_STRING>" -H 'Content-Type: application/json'
-d '{"log":"false","execute":"","resolution":"deny","description":"Rule to modify the another one","rule_id":200,"skip":"1","phase":4,"skip_after":12,"tag":["testing 2","Api tests 2"]}'
https://<zevenet_server>:444/zapi/v4.0/zapi.cgi/ipds/waf/test_waf_ori/rules/0

PUT /ipds/waf/<name>/rule/<id>

Modify the parameters of a WAF rule.

The name is the WAF ruleset unique identifier.

The URI parameter id is the rule id. It listed as id in the rule object.

This call can work with three sets of parameters different.

Request parameters:

Field Type Description
rule_id Number It is the rule identifier. It must be unique in the system. It is used to copy a rule. This parameter is only to rules of type action. If two rule sets contain a rule with the same rule_id won’t be able to link with the same farm.
resolution String To execute this action, it is necessary to have configured the ruleset parameter status to true. This parameter is the action to apply when a WAF rule matches. The possible values are: pass, the rule will apply the other options configured (log, execute…) and the request won’t be cut. The following rules will be checked; deny, ends the connection, the following rules won’t be executed; redirect, the client will be redirected to the URL configured in the parameter redirect_url; default_action, the rule will execute the action that was set in the ruleset parameter default_action.
audit String This parameter overwritten the audit set rule parameter for the current rule in the case the rule matches. If it has the value true, the rule will always report in the audit log; If it has the value false, in the case that a match, the rule will never report to the audit log; if the default behavior is desired, set as blank string.
description String It is a descriptive message for the rule.
execute String It is the path to an LUA script. This script will be executed when the rule matches. The script must exist before configuring this parameter.
log String If this parameter has the value true, the rule will log in a successful match. To not log, the parameter has to be set with the value false. If the value is set to blank the ruleset parameter default_log will be executed.
log_data String This parameter allows logging additional information. It can be used with variables to log any interesting transaction information.
phase String The phase represents the point of the HTTP request where a rule will be executed. The possible values are 1, it is executed when the request headers are received; 2, it is executed when the body request is received; 3, it is executed when the response headers are received; 4, it is executed when the response body is received; or 5, it is executed just before logging.
redirect_url String It is the URL where redirecting the client in the case that the resolution redirect is executed. This parameter can be set only when the rule resolution has the value redirect.
skip Number It is the number of rules to skip when the rule matches. The skipped rules are in the same phase.
skip_after String This parameter has two possible kinds of values: a rule_id, in a successful match, WAF jumps to the rule_id selected; or a “string”, the string must be an existing mark, all rules will skip until reaching the mark. The skip_after parameter works only over rules in the same phase.
tag String[] The tags are marks to classify the matched traffic.
Field Type Description
raw String This field contains the rule in SecLang syntax.
Field Type Description
mark String It is a name for the mark. It will be used to use it.

Response example:

{
          "params" : {
                        "rule_id" : "200",
                        "execute" : "",
                        "type" : "action",
                        "skip_after" : "12",
                        "matches" : [],
                        "redirect_url" : "",
                        "skip" : "1",
                        "modified" : "yes",
                        "resolution" : "deny",
                        "description" : "Rule to modify the another one",
                        "audit" : "false",
                        "log" : "",
                        "id" : 0,
                        "tag" : [
                                   "testing 2",
                                   "Api tests 2"
                                 ],
                        "raw" : "SecAction \"\\
    id:200,\\
    msg:\'Rule to modify the another one\',\\
    tag:testing 2,\\
    tag:Api tests 2,\\
    phase:4,\\
    deny,\\
    noauditlog,\\
    skip:1,\\
    skipAfter:12\"",
                        "phase" : 4
                      }
}

Response parameters

The response will be a JSON object with the param key set. The value will be the WAF rule object updated.

Move a WAF rule in a WAF set

Move a WAF rule in a WAF set

POST /ipds/waf/<name>/rules/<id>actions

The URI parameter name is the set name. It is used as a unique identifier.

The URI parameter id is the rule id. It listed as id in the rule object.

This call is to change the position of a WAF rule in a WAF set. The order in which the rules appear is the same in they are executed.

Request example:

curl -k -X POST -H "ZAPI_KEY: <ZAPI_KEY_STRING>" -H 'Content-Type: application/json'
-d '{"position":"2"}'
https://<zevenet_server>:444/zapi/v4.0/zapi.cgi/ipds/waf/test_waf_ori/rules/0/actions

Request parameters

Field Type Description Required
position Number It is the position to put the WAF ruleset. true

Request example to create a mark rule:

{
          "message" : "The rule was moved properly to the position 2.",
          "description" : "Move a rule in the set test_waf_ori"
}

Delete a WAF rule

Delete a WAF rule

Request example:

curl -k -X DELETE -H "ZAPI_KEY: <ZAPI_KEY_STRING>"
https://<zevenet_server>:444/zapi/v4.0/zapi.cgi/ipds/waf/test_waf_ori/rules/0

DELETE /ipds/waf/<name>/rules/<id>

Delete a given WAF rule in a set.

The name is the WAF rule set a unique identifier.

The id is the field listed in the field id of a rule.

Response example:

{
          "message" : "The rule 0 has been deleted properly",
          "description" : "Delete the rule 0 from the set test_waf_ori"
}

Create a match in a WAF rule

Create a match in a WAF rule

Request example:

curl -k -X POST -H "ZAPI_KEY: <ZAPI_KEY_STRING>" -H 'Content-Type: application/json'
-d '{"not_match":"true","multi_match":"false","transformations":["replaceComments","removeCommentsChar"],"capture":"true","variables":["!RESPONSE_BODY"],"operating":"","operator":"detectSQLi"}'
https://<zevenet_server>:444/zapi/v4.0/zapi.cgi/ipds/waf/test_waf_ori/rules/0/matches

POST /ipds/waf/<name>/rules/<id>/matches

A matching rule extends a WAF action rule, adding new match conditions.

Create a match rule in a WAF rule.

The name URI parameter is the ruleset name, its unique identifier.

The id URI parameter is the id field in a rule object, its unique identifier.

Request parameters

Field Type Description
not_match String It is used to indicate that the rule should not match with the condition.
capture String This parameter enables the feature of capturing the value obtained from a regular expression. To use this parameter with sense, it has to be used with the operator strRegexp. The possible values are true or false.
multi_match String This parameter is used when more than one transformations are configured. The rule will try a match of the variables, the operator and the operating for each value of transformations. The possible values are: true, enables multi match; or false, disables the multi match feature.
transformations String[] The transformation modifies the variables before than apply them to the operator and operating. This parameter is useful to remove anti-avoid techniques or to remove codification data. Here, there is list of the transformation.
variables String[] It is against which part of the HTTP transaction the rule will try the match. The possible values are in this table.
operator String It is how the rule tries the match. This parameter is used combined with operating. The type of value expected depend on the operator table.
operating String It is what the rules try in the match. The parameter is used combined with operator.

Response example:

{
          "message" : "The new match was created successfully.",
          "params" : {
                        "not_match" : "false",
                        "multi_match" : "false",
                        "raw" : "SecRule REQUEST_METHOD \"@streq GET\" \"\\
    id:9001185,\\
    phase:1,\\
    t:none,\\
    pass,\\
    nolog,\\
    noauditlog,\\
    chain\"
SecRule !RESPONSE_BODY \"!@detectSQLi \" \"\\
    msg:\'Custom Match\',\\
    t:replaceComments,\\
    t:removeCommentsChar,\\
    capture\"",
                        "operating" : "",
                        "variables" : [
                                         "!RESPONSE_BODY"
                                       ],
                        "operator" : "detectSQLi",
                        "transformations" : [
                                               "replaceComments",
                                               "removeCommentsChar"
                                             ],
                        "capture" : "true",
                        "match_index" : 1
                      },
          "description" : "Create a match in the rule 0 for the set test_waf_ori"
}

Response parameters

The response will be a JSON object with a key set to params. The value is the rule object updated.

Field Type Description
raw String This field contains a string with the rule in SecLang syntax.
match_index Number It is the index of the match object. It is used as the unique identifier inside of the match list of the rule.
not_match String It is used to indicate that the rule should not match with the condition.
capture String This parameter enables the feature of capturing the value obtained from a regular expression. To use this parameter with sense, it has to be used with the operator strRegexp. The possible values are true or false.
multi_match String This parameter is used when more than one transformations are configured. The rule will try a match of the variables, the operator and the operating for each value of transformations. The possible values are: true, enables multi match; or false, disables the multi match feature.
transformations String[] The transformation modifies the variables before than apply them to the operator and operating. This parameter is useful to remove anti-avoid techniques or to remove codification data. Here, there is list of the transformation.
variables String[] It is against which part of the HTTP transaction the rule will try the match. The possible values are in this table.
operator String It is how the rule tries the match. This parameter is used combined with operating. The type of value expected depend on the operator table.
operating String It is what the rules try in the match. The parameter is used combined with operator.

Modify a match in a WAF rule

Modify a match in a WAF rule

Request example:

curl -k -X PUT -H "ZAPI_KEY: <ZAPI_KEY_STRING>" -H 'Content-Type: application/json'
-d '{"capture":"false","transformations":["replaceComments","removeCommentsChar"],"multi_match":"true","not_match":"false","variables":["RESPONSE_HEADERS_NAMES"]}'
https://<zevenet_server>:444/zapi/v4.0/zapi.cgi/ipds/waf/test_waf_ori/rules/0/matches/0

PUT /ipds/waf/<name>/rules/<id>/matches/<id>

A matching rule extends a WAF action rule, adding match conditions.

Create a match rule in a WAF rule.

The name URI parameter is the ruleset name, its unique identifier.

The first id URI parameter is the id field in a rule object, its unique identifier.

The second id URI parameter is the index of the match in the field match_index of the rule.

Request parameters

Field Type Description
not_match String It is used to indicate that the rule should not match with the condition.
capture String This parameter enables the feature of capturing the value obtained from a regular expression. To use this parameter with sense, it has to be used with the operator strRegexp. The possible values are true or false.
multi_match String This parameter is used when more than one transformations are configured. The rule will try a match of the variables, the operator and the operating for each value of transformations. The possible values are: true, enables multi match; or false, disables the multi match feature.
transformations String[] The transformation modifies the variables before than apply them to the operator and operating. This parameter is useful to remove anti-avoid techniques or to remove codification data. Here, there is list of the transformation.
variables String[] It is against which part of the HTTP transaction the rule will try the match. The possible values are in this table.
operator String It is how the rule tries the match. This parameter is used combined with operating. The type of value expected depend on the operator table.
operating String It is what the rules try in the match. The parameter is used combined with operator.

Response example:

{
          "params" : {
                        "transformations" : [
                                               "replaceComments",
                                               "removeCommentsChar"
                                             ],
                        "capture" : "false",
                        "match_index" : 0,
                        "multi_match" : "true",
                        "not_match" : "false",
                        "variables" : [
                                         "RESPONSE_HEADERS_NAMES"
                                       ],
                        "operator" : "strEq",
                        "operating" : "GET",
                        "raw" : "SecRule RESPONSE_HEADERS_NAMES \"@streq GET\" \"\\
    id:9001185,\\
    msg:\'Custom Match\',\\
    phase:1,\\
    t:replaceComments,\\
    t:removeCommentsChar,\\
    multimatch,\\
    pass,\\
    nolog,\\
    noauditlog,\\
    chain\"
SecRule !RESPONSE_BODY \"!@detectSQLi \" \"\\
    msg:\'Custom Match\',\\
    t:replaceComments,\\
    t:removeCommentsChar,\\
    capture\""
                      },
          "description" : "Modify the match 0 in rule 0 for the set test_waf_ori"
}

Response parameters

The response will be a JSON object with a key set to params. The value is the rule object updated.

Field Type Description
raw String This field contains a string with the rule in SecLang syntax.
match_index Number It is the index of the match object. It is used as the unique identifier inside of the match list of the rule.
not_match String It is used to indicate that the rule should not match with the condition.
capture String This parameter enables the feature of capturing the value obtained from a regular expression. To use this parameter with sense, it has to be used with the operator strRegexp. The possible values are true or false.
multi_match String This parameter is used when more than one transformations are configured. The rule will try a match of the variables, the operator and the operating for each value of transformations. The possible values are: true, enables multi match; or false, disables the multi match feature.
transformations String[] The transformation modifies the variables before than apply them to the operator and operating. This parameter is useful to remove anti-avoid techniques or to remove codification data. Here, there is list of the transformation.
variables String[] It is against which part of the HTTP transaction the rule will try the match. The possible values are in this table.
operator String It is how the rule tries the match. This parameter is used combined with operating. The type of value expected depend on the operator table.
operating String It is what the rules try in the match. The parameter is used combined with operator.

Delete a match of a WAF rule

Delete a match of a WAF rule

Request example:

curl -k -X DELETE -H "ZAPI_KEY: <ZAPI_KEY_STRING>"
https://<zevenet_server>:444/zapi/v4.0/zapi.cgi/ipds/waf/test_waf_ori/rules/0/matches/0

DELETE /ipds/waf/<name>/rules/<id>/matches/<id>

Delete a match of a WAF rule.

The URI parameter name is the WAF unique identifier.

The first id URI parameter is the id field in a rule object, its unique identifier.

The second id URI parameter is the index of the match in the field match_index of the rule.

Response example:

{
          "description" : "Delete the match 0 from rule 0 for the set test_waf_ori",
          "message" : "The match 0 has been deleted properly",
          "params" : {
                        "raw" : "SecAction \"\\
    id:9001185,\\
    msg:\'Custom Match\',\\
    phase:1,\\
    t:replaceComments,\\
    t:removeCommentsChar,\\
    multimatch,\\
    pass,\\
    nolog,\\
    noauditlog,\\
    chain\"
SecRule !RESPONSE_BODY \"!@detectSQLi \" \"\\
    id:1,\\
    msg:\'Custom Match\',\\
    t:replaceComments,\\
    t:removeCommentsChar,\\
    capture\""
                      }
}

Response parameters

The response will be a JSON object with the key set to params. The value is the rule object updated without the deleted matches.

Move a WAF rule set in a farm

Move a WAF rule set in a farm

POST /farms/<farm>/ipds/waf/<name>/actions

The URI parameter farm is the farm name. It is used as a unique identifier.

The URI parameter name is the set name. It is used as a unique identifier.

This call is to change the position of a WAF set inside a farm configuration. The order in which the sets appear is the same in they are executed.

Request example:

curl -k -X POST -H "ZAPI_KEY: <ZAPI_KEY_STRING>" -H 'Content-Type: application/json'
-d '{"position":"0"}'
https://<zevenet_server>:444/zapi/v4.0/zapi.cgi/farms/httpTest/ipds/waf/test_waf_copied/actions

Request parameters

Field Type Description Required
position Number It is the position to put the WAF ruleset. true

Request example to create a mark rule:

{
          "message" : "The set was moved properly to the position 0.",
          "description" : "Move a set in farm"
}

Apply an action to a WAF ruleset

Apply an action

Request example:

curl -k -X POST -H 'Content-Type: application/json' -H "ZAPI_KEY: <ZAPI_KEY_STRING>"
-d '{"action":"start"}'
https://<zevenet_server>:444/zapi/v4.0/zapi.cgi/ipds/waf/test_waf_copied/actions

POST /ipds/waf/<name>/actions

Apply an action to a WAF. name is the WAF unique identifier.

Request parameters

Field Type Description Required
action String Action desired to apply to a WAF ruleset. The available values are: start, it actives the WAF rule set in all farms where it is applied; stop, it stops the WAF rule set for all farms where the rule set is applied, the rules won’t inspect the incoming traffic. true

Response example:

{
          "description" : "Apply a action to the set rule test_waf_copied",
          "success" : "true",
          "params" : {
                        "status" : "up"
                      }
}

Response parameters

The response will be a JSON with the download status. See the response example for more information.

Field Type Description Required
status String Status of the WAF ruleset after applying the requested action.

System

System options offer you the possibility of personalizing 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/v4.0/zapi.cgi/system/version

GET /system/version

Show information 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 Appliance version. Show also hypervisor if is a virtual machine.
hostname String Hostname.
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/v4.0/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 the system.
secondary String Secondary DNS configurated in the 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/v4.0/zapi.cgi/system/dns

POST /system/dns

Modify the DNS service configuration.

Request parameters

Field Type Description
primary String Primary DNS configurated in the system.
secondary String Secondary DNS configurated in the 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 the 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/v4.0/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 access 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/v4.0/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 access 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 the 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/v4.0/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/v4.0/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/v4.0/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 the 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/v4.0/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 the 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/v4.0/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 the system where the 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 the 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/v4.0/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 is the IP where the HTTP service 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/v4.0/zapi.cgi/system/http

POST /system/http

Modify the HTTP service configuration.

Request parameters

Field Type Description
ip String is the IP where the HTTP service 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 the response example for more information.

Show Proxy server

Show Proxy server

Request example:

curl -k -X GET -H "ZAPI_KEY: <ZAPI_KEY_STRING>"
https://<zevenet_server>:444/zapi/v4.0/zapi.cgi/system/proxy

GET /system/proxy

Show the configuration about HTTP/HTTPS remote services. This proxy will be used to the remote HTTP request from the load balancer (as downloading IPDS rules and getting packages updates).

Response example:

{
          "description" : "Get proxy configuration",
          "params" : {
                        "https_proxy" : "https://10.10.10.12:8888",
                        "http_proxy" : "http://10.10.10.12:8888"
                      }
}

Response parameters

The response will be a JSON object with the below parameters.

Field Type Description
http_proxy String It is the remote proxy server to send the requests that use the HTTP protocol, without SSL encryption.
https_proxy String It is the remote proxy server to send the requests that use the HTTPS protocol, with SSL encryption.

Modify Proxy

Modify Proxy

Request example:

curl -k -X POST -H 'Content-Type: application/json' -H "ZAPI_KEY: <ZAPI_KEY_STRING>"
-d '{"http_proxy":"http://10.10.10.12:8888","https_proxy":"https://10.10.10.12:8888"}'
https://<zevenet_server>:444/zapi/v4.0/zapi.cgi/system/proxy

POST /system/http

Modify the HTTP service configuration.

Request parameters

Field Type Description
http_proxy String It is the URL to the remote proxy server to send the requests that use the HTTP protocol, without SSL encryption.
https_proxy String It is the URL to the remote proxy server to send the requests that use the HTTPS protocol, with SSL encryption.

Response example:

{
          "http_proxy" : "http://10.10.10.12:8888",
          "https_proxy" :"https://10.10.10.12:8888"
}

Response parameters

The response will be a JSON with all requested values updated. See the response example for more information.

Retrieve the current user

Retrieve the current user

Request example:

curl -k -X GET -H "ZAPI_KEY: <ZAPI_KEY_STRING>"
https://<zevenet_server>:444/zapi/v4.0/zapi.cgi/system/users

GET /system/users

Show information about the current user. The current user is the user got from the ZAPI_KEY or the user logged by the WebGUI

Response example:

{
   "description" : "Retrieve the user root",
   "params" : {
      "user" : "root",
      "zapi_permissions" : "true"
   }
}

Response parameters

The response will be a JSON object with an array of the below parameters.

Field Type Description
user String It is the user owner of the ZAPI_KEY. It can be the root default user or an RBAC user.
zapi_permissions String If the value is true, the user can use the Zevenet API though the user’s zapikey; or if the value is false, the user has disabled the to use the ZAPI.

Modify the current user

Modify the current user

Request example:

curl -k -X POST -H 'Content-Type: application/json' -H "ZAPI_KEY: <ZAPI_KEY_STRING>"
-d '{"password":"CDe0c3ck","newpassword":"v2mfcvv2","zapi_permissions":"false","zapikey":"vCeH60mQFf2MgH5"}'

https://<zevenet_server>:444/zapi/v4.0/zapi.cgi/system/users

POST /system/users

Modify the configuration of the current user. The current user is the user got from the ZAPI_KEY or the user logged by the WebGUI.

Request parameters:

Field Type Description Required
zapikey String Each user can have a zapikey. With this zapikey, the user can do action through the zapikey with the permissions of the user’s role.
zapi_permissions String The possible values are: true, to enable the access to the load balancer through the ZAPI; or false, to deny the access through the ZAPI.
newpassword String New user password to access through the WebGUI.
password String is the current user password. It is required when newpassword is sent.

Response example:

{
   "description" : "Modify the user Shadi",
   "message" : "Settings was changed successful."
}

List log files

List log files

Request example:

curl -k -X GET -H "ZAPI_KEY: <ZAPI_KEY_STRING>"
https://<zevenet_server>:444/zapi/v4.0/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 the 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 a 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/v4.0/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 lines of the log file. The key is log and its value is an 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/v4.0/zapi.cgi/system/logs/syslog.2.gz > log.gz

GET /system/logs/<file>

Download a log file of the available log files listed while the 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/v4.0/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 a 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/v4.0/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 a 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/v4.0/zapi.cgi/system/backup/firstConf > ~/zevenetConf.tar.gz

The backup file is in the 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/v4.0/zapi.cgi/system/backup/newbackup

PUT /system/backup/<name>

Upload a locally 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/v4.0/zapi.cgi/system/backup/firstConf

DELETE /system/backup/<name>

Delete a backup file from the 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/v4.0/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"
   }
}

Download a supportsave

Download a supportsave

Request example:

curl -k -X GET -H "ZAPI_KEY: <ZAPI_KEY_STRING>"
https://<zevenet_server>:444/zapi/v4.0/zapi.cgi/system/supportsave > supportsave.tar.gz

GET /system/supportsave

Get the system status image with all configuration and process running in the system. This supportsave it is necessary to find issues or support assistance.

List available updates

List available updates

Request example:

curl -k -X GET -H "ZAPI_KEY: <ZAPI_KEY_STRING>"
https://<zevenet_server>:444/zapi/v4.0/zapi.cgi/system/packages

GET /system/packages

List the updates available. The response contains the command line to update the packages.

Response example:

{
   "description" : "Zevenet packages list info",
   "params" : {
      "last_check" : "Sun 09 Jun 2019 10:00:02 PM UTC",
      "message" : "To upgrade the system, please, execute in a shell the following command:\n\t'apt-get --with-new-pkgs upgrade'",
      "number" : 9,
      "packages" : [
         "health-checks",
         "librrds-perl",
         "nftables",
         "nftlb",
         "rrdtool",
         "ssyncd",
         "unzip",
         "zevenet-base-files"
      ],
      "status" : "Updates available"
   }
}

Response parameters

The response will be a JSON object with an array of the below parameters.

Field Type Description
last_check String Message with the date of the last repository check.
message String Message with the command line to update the packages.
number Number Number of available updates.
packages String[] List of package names that are going to be updated.
status String Message with the package status.

Factory Reset

Factory Reset

Request example:

curl -k -X POST -H 'Content-Type: application/json' -H "ZAPI_KEY: <ZAPI_KEY_STRING>"
-d '{"force":"true","interface":"eth0"}'
https://<zevenet_server>:444/zapi/v4.0/zapi.cgi/system/factory

POST /system/factory

Apply a factory reset in the system. It will delete all the user configuration. The root password, the hostname, one NIC interface and the certificate will not be modified. The system will be restarted while the process is going on.

Request parameters

Field Type Description Required
interface String It is a NIC interface name. This interface will not be deleted in the factory reset process. The system will be available before factory reset through this interface. true
force String It is a confirmation about to apply the factory reset. This parameter has to be sent with true value for applying it. true
remove_backups String It is an option about remove all system backups. They will not be removed by default. If this parameter is set to true, the backups will be removed.

Response example:

{
      "description" : "Apply a factory reset",
      "message" : "The factory reset was applied properly. The session will be lost. Please, try again in a while"
}

System - Notifications

Notifications are formed by two elements: Sender method and type of alert.

In the alert section, you will be able to choose which type of alert you wish to receive. The alerts are focused on backend or cluster status, so the balancer will send a notification if some switches.

In the 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/v4.0/zapi.cgi/system/notifications/alerts

GET /system/notifications/alerts

List all types 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 an 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 switches to another node.
status String Show if the alert is disabled, the system doesn’t send a notification when there is an event; or enabled, the system sends an 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/v4.0/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, this field allows to configure a time to avoid notifications message while the backend is changing status, once this time concludes, if the backend status it is 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 the alert is disabled, the system doesn’t send a notification when there is an event; or enabled, the system sends an 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/v4.0/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, this field allows to configure a time to avoid notifications message while the backend is changing status, once this time concludes, if the backend status it is different to start, then the notification is sent. This parameter is not in cluster alerts, the cluster has its own switch 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 the 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>"
-d '{"action":"enable"}'
https://<zevenet_server>:444/zapi/v4.0/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 disable, the system doesn’t send a notification when there is an event; or enable, the system sends an 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 the 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/v4.0/zapi.cgi/system/notifications/methods/email

GET /system/notifications/methods/email

Show all the configuration of the 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 receiver replies the email.
method String It is the method unique identifier. 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 an email, this property uses STARTTLS and this feature has to be supported in the SMTP server. Some SMTP servers require to 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 the 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/v4.0/zapi.cgi/system/notifications/methods/email

POST /system/notifications/methods/email

Modify the configuration of the 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 receiver 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 an email, this property uses STARTTLS and this feature has to be supported in the SMTP server. Some SMTP servers require to 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 the 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 the 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/v4.0/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"
}

System - Cluster

The cluster is the element done by a master node, that it manages the connections forward the backends, and a backup node checking the master, it is prepared to switch to the 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, the client does not detect an interruption in the service.

This lets put the load balancer in high availability. So if there is 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/v4.0/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 the 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 the 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’s hostname, and it is used as node unique identifier.
node String If this field is local, the object configuration is the node is managing the ZAPI call. If it is remote, the information is about a remote node.

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/v4.0/zapi.cgi/system/cluster

POST /system/cluster

Do a cluster communicating two balancers.

Request parameters

Field Type Description Required
remote_ip String IP of a remote host used to the cluster. true
local_ip String IP of the 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/v4.0/zapi.cgi/system/cluster

PUT /system/cluster

Configure working mode parameters for the 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 the 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/v4.0/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/v4.0/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/v4.0/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 the node unique identifier.
node String If this field is local, the object configuration is the node is managing the ZAPI call. If it is remote, the information is about a remote node.
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/v4.0/zapi.cgi/system/cluster/nodes/localhost

GET /system/cluster/nodes/localhost

Show the status of the 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 the 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.

RBAC

RBAC is the solution for a Role Based Access Control. So, Zevenet can be managed and administrate by different roles, restricting the access to configurations and resources for groups.

A group can see the resources (farms and virtual interfaces) that is the owner. It is possible to define different permission to apply actions about resources, then, for example, a group could manage a farm and another one could monitor it.

Three elements are used to work with RBAC: roles, a role is a set of permission for different load balancer’s elements. users, each user will be able to access the load balancer for ZAPI, for WebGUI or both, with the role of the user’s group. group, it is a set of users and a set of resources (farms and virtual interfaces). A group must have a role assigned.

RBAC - Users

A user can access the load balancer with the role of the user’s group through the ZAPI, with the user’s zapikey and applying it ZAPI permissions, or through the WebGUI with the user name and the password if the user has WebGUI permissions.

List the users

List all the users

Request example:

curl -k -X GET -H "ZAPI_KEY: <ZAPI_KEY_STRING>"
https://<zevenet_server>:444/zapi/v4.0/zapi.cgi/rbac/users

GET /rbac/users

List all the RBAC users and their configurations

Response example:

{
   "description" : "List the RBAC users",
   "params" : [
      {
         "group" : "monitor",
         "name" : "sarah",
         "webgui_permissions" : "true",
         "zapi_permissions" : "true"
      },
      {
         "group" : "system-admin",
         "name" : "john",
         "webgui_permissions" : "true",
         "zapi_permissions" : "true"
      },
      {
         "group" : "web-admin",
         "name" : "aaron",
         "webgui_permissions" : "true",
         "zapi_permissions" : "false"
      }
   ]
}

Response parameters

The response will be a JSON object with a key set to params. The value of this will be an array of user objects, each of which contains the key attributes below.

Field Type Description
group String It is the group name where the user is. The user can be only in one group.
name String User name, it identifies to the user and it used to access through the WebGUI.
webgui_permissions String The possible values are: true, to enable the access to the load balancer through the WebGUI; or false, to not allow accessing through the WebGUI.
zapi_permissions String The possible values are: true, to enable the access to the load balancer through the ZAPI; or false, to not allow the access through the ZAPI.

Retrieve a user

Retrieve a user

Request example:

curl -k -X GET -H "ZAPI_KEY: <ZAPI_KEY_STRING>"
https://<zevenet_server>:444/zapi/v4.0/zapi.cgi/rbac/users/sarah

GET /rbac/users/<name>

Show the user configuration. name is the user name and it is a unique identifier.

Response example:

{
   "description" : "Get the user sarah",
   "params" : {
         "group" : "monitor",
         "name" : "sarah",
         "webgui_permissions" : "true",
         "zapi_permissions" : "true"
      }
}

Response parameters

The response will be a JSON object with a key set to params. The value of this will be an array of user objects, each of which contains the key attributes below.

Field Type Description
group String It is the group name where the user is. The user can be only in one group.
name String User name, it identifies to the user and it used to access through the WebGUI.
webgui_permissions String The possible values are: true, to enable the access to the load balancer through the WebGUI; or false, to not allow accessing through the WebGUI.
zapi_permissions String The possible values are: true, to enable the access to the load balancer through the ZAPI; or false, to not allow accessing through the ZAPI.

Create a user

Create a new user

Request example:

curl -k -X POST -H "ZAPI_KEY: <ZAPI_KEY_STRING>" -H 'Content-Type: application/json'
-d '{ "name":"monica","password":"aCX2kl5m9"}'
https://<zevenet_server>