RELIANOID API v4.0 Reference
ZAPI (Zevenet Application Programming Interface) is the tool for system administrators to control the RELIANOID 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://relianoid_server
:444/api/v4.0/api.cgi/URI_path
,
where relianoid_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 RELIANOID object will be defined within each documentation section.
The HTTP verbs
accepted for the ZAPI are:
GET, is used to get a list of elements or to retrieve an object.
POST, is used to create new objects, modify system object (objects that the admin has not got created) and to apply actions.
PUT, is used to modify an existing object that was created by the admin.
DELETE, is used to remove an object that was created by the admin and in some case to reset a configuration (case of interfaces).
ZAPI parameters
ZAPI parameters
Request example:
curl -k -X POST -H "ZAPI_KEY: <ZAPI_KEY_STRING>"
-H 'Content-Type: application/json' -d ''
https://<relianoid_server>:444/api/v4.0/api.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.2
This ZAPI version is a extension of the version 4.0.1. Some parameters and URIs were added but any of them where removed.
- VPN
New VPN module:
Added GET|POST|PUT|DELETE /vpns/*
- HTTP/S Farms
New params:
errorWAF, rewritelocation(added new options only for zproxy), rewriteurl, pinnedconnection, routingpolicy, connection_limit:
Modified: GET|PUT /farms/<farmname>
.
Modified: GET|PUT /farms/<farmname>/services/<id>
.
New APIs to add rewriteurl:
Added ADD|DELETE /farms/<farmname>/service/<servicename>/rewriteurl/*
New APIs to add Rewrite Headers Rules:
Added ADD|DELETE /farms/MyHttpFarm/replacerequestheader/*
Added ADD|DELETE /farms/MyHttpFarm/replaceresponseheader/*
Added requests to manage static sessions (zproxy only):
Added GET|POST|DELETE /farms/<farmname>/services/<servicename>/sessions/*
- Farmguardian
Added parameter timeout:
Modified: GET /monitoring/fg/<name>
.
Modified: POST|PUT /monitoring/fg
.
- SSH
Configure multiple ips and ports:
Modified ADD|POST /system/ssh
, now accept arrays in the listen and port params.
- HTTP Server:
Configure multiple ips and ports for cherokee server:
Modified ADD|POST /system/http
, now accept arrays in the ip and port params.
Configure the server certificate:
Added GET|POST /system/https/certificate
.
- Statistics:
Added parameters total_sessions and ttl:
Modified: GET /stats/farms/<farmname>
- Global configuration:
Added parameter waf_assistant:
Modified GET|POST /system/global
- Rsyslog
New rsyslog APIs to configure logs to send them to remote server:
Added: GET|POST|DELETE /system/rsyslog
.
- Cluster:
Added parameter track_interface:
Modified: GET|PUT /system/cluster
.
API 4.0.1
This ZAPI version is a extension of the version 4.0. Some parameters and URIs were added but any of them where removed.
- IDs
Add a request to show a tree with all objects of the load balancer
Add: GET /ids
- Farms
Option to copy a farm
Modified: POST /farms
- HTTP Farms
Add parameters addresponseheader and removeresponseheader and extend the parameter httpverb:
Modified GET /farms/<farmname>
Modified PUT /farms/<farmname>
Add POST /farms/<farmname>/addresponseheader|removeresponseheader
Add DELETE /farms/<farmname>/addresponseheader|removeresponseheader/<n>
- L4xNAT Farms
Add requests to manage static sessions:
Add GET /farms/<farmname>/sessions
Add POST /farms/<farmname>/sessions
Add DELETE /farms/<farmname>/sessions/<session>
- Networking
New module of routing:
Added GET|POST|PUT|DELETE /routing/*
- Monitoring
Farmguardian can use the backend alias as host name for checks:
Added GET|PUT /monitoring/fg*/<farmguardian>
- IPDS
Manage files for WAF rules:
Added GET|PUT|DELETE /ipds/waf/files
- System
Get system information:
Added: GET /system/info
Modified global settings:
Added: GET|POST /system/global
- RBAC
Authentication using LDAP:
Added GET|POST /rbac/services
Added GET|POST /rbac/ldap*
Modified GET|POST /rbac/users
Modified GET|PUT /rbac/users/<user>
API 4.0
- HTTP Farms
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
- L4xNAT Farms
Modify farms call related with l4xnat to support the new core:
Modified: GET|POST|PUT|DELETE /farms/<l4farm>
- Network
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>
- Monitoring
Rename parameter to copy a farm guardian:
Modified: POST /monitoring/fg
- IPDS
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>
- System
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
- RBAC
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 RELIANOID 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://<relianoid_server>:444/api/v4.0/api.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://<relianoid_server>:444/api/v4.0/api.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://<relianoid_server>:444/api/v4.0/api.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
RELIANOID 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://<relianoid_server>:444/api/v4.0/api.cgi/certificates
zcli certificate list
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://<relianoid_server>:444/api/v4.0/api.cgi/certificates/example.pem
zcli certificate download 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://<relianoid_server>:444/api/v4.0/api.cgi/certificates/example.pem/info
zcli certificate get example.pem
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://<relianoid_server>:444/api/v4.0/api.cgi/certificates/example.pem
zcli certificate delete 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 PEM certificate
Create a PEM certificate
Request example:
curl -k -X POST -H "ZAPI_KEY: <ZAPI_KEY_STRING>" -H 'Content-Type: application/json'
-d '{"name":"host.domain.com","key":"-----BEGIN PRIVATE KEY-----\nRTQwew...",
"ca","-----BEGIN CERTIFICATE-----\nFQOEW...","intermediates":"-----BEGIN CERTIFICATE-----\nQWESw..."}'
https://<relianoid_server>:444/api/v4.0/api.cgi/certificates/pem
zcli certificate-pem create -name host.domain.com -key "-----BEGIN PRIVATE KEY..." -ca "-----BEGIN CERTIFICATE..." -intermediates "-----BEGIN CERTIFICATE..."
"
POST /certificates/pem
Create a PEM Certificate (PEM file).
Request parameters
Field | Type | Description | Required |
---|---|---|---|
name | String | Certificate ID name. | true |
key | String | No Encrypted Private Key | true |
ca | String | Server Certificate or fullchain Certificate | true |
intermediates | String | Intermediate Certificates if needed | false |
Response example:
{
"description" : "Create certificate",
"message" : "Certificate host.domain.com created",
"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://<relianoid_server>:444/api/v4.0/api.cgi/certificates
zcli certificate create -name NewCSR -fqdn host.domain.com -division IT -organization 'Example Corp.' -locality Madrid -state Madrid -country ES -mail info@domain.com
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 |
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://<relianoid_server>:444/api/v4.0/api.cgi/certificates/example.pem
zcli certificate upload example.pem /local_path/to/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"
}
Letsencrypt SSL Certificates
RELIANOID supports Letsencrypt certificates generation and renew. The finally certificate is a RELIANOID PEM certificate can be used with HTTPS Farms. . If you want to learn more about how to create pem certificates, please visit the following article: GENERATE CERTIFICATES IN PEM FORMAT
Show Letsencrypt Config
Show Letsencrypt Config
Request example:
curl -k -X GET -H "ZAPI_KEY: <ZAPI_KEY_STRING>"
https://<relianoid_server>:444/api/v4.0/api.cgi/certificates/letsencryptz/config
zcli certificate-le-config list
GET /certificates/letsencryptz/config
Show Letsencrypt Configuration.
Response example:
The response will be a JSON object with the below parameters.
{
"description" : "Get LetsEncrypt Config",
"params" : {
"email" : "test_le@relianoid.com"
}
}
Response parameters
Field | Type | Description |
---|---|---|
String | Email for Letsencrypt |
Modify Letsencrypt Config
Modify Letsencrypt Config
Request example:
curl -k -X PUT -H "ZAPI_KEY: <ZAPI_KEY_STRING>"
-d '{"email":"test_le@relianoid.com"}'
https://<relianoid_server>:444/api/v4.0/api.cgi/certificates/letsencryptz/config
zcli certificates-le-config set -email test_le@relianoid.com
PUT /certificates/letsencryptz/config
Modify Letsencrypt Configuration.
Request parameters
Field | Type | Description | Required |
---|---|---|---|
String | Email for use as a contact in Letsencrypt | true |
Response example:
The response will be a JSON object with the below parameters.
{
"description" : "Modify LetsEncrypt Config",
"message" : "The Letsencrypt Config has been updated successfully.",
"params" : {
"email" : "test_le@relianoid.com"
},
"success" : "true"
}
Response parameters
Field | Type | Description |
---|---|---|
String | Email for Letsencrypt |
List all Letsencrypt Certificates
List all Letsencrypt Certificates
Request example:
curl -k -X GET -H "ZAPI_KEY: <ZAPI_KEY_STRING>"
https://<relianoid_server>:444/api/v4.0/api.cgi/certificates/letsencryptz
zcli certificate-le list
GET /certificates/letsencryptz
List all Letsencrypt certificates created.
Response example:
The response will be a JSON object with a key set to params. The value of this will be an array of letsencrypt certificate objects, each of which contains the key attributes below.
{
"description" : "List LetsEncrypt certificates",
"params" : [
{
"CN" : "*.wildcard.test.relianoid.com",
"creation" : "May 31 05:51:49 2021 GMT",
"domains" : [
"*.wildcard.test.relianoid.com"
],
"expiration" : "Aug 29 05:51:49 2021 GMT",
"file" : "/usr/local/relianoid/config/letsencrypt/acme/*.wildcard.test.relianoid.com/fullchain.cer",
"issuer" : "US,(STAGING) Let's Encrypt,(STAGING) Artificial Apricot R3",
"status" : "valid",
"type" : "LE Certificate",
"wildcard" : "true"
},
{
"CN" : "*.test1.wildcard.test.relianoid.io",
"creation" : "",
"dnstxt" : [
{
"domain" : "*.test1.wildcard.test.relianoid.io",
"txt" : "QpbOLzMrJapoQmcbrA5_dr6ciwLzNF-y3z5XR5i-I2c"
}
],
"domains" : [
"*.test1.wildcard.test.relianoid.io"
],
"expiration" : "",
"file" : null,
"issuer" : "",
"status" : "not issued",
"type" : "LE Certificate",
"wildcard" : "true"
}
]
}
Response parameters
Field | Type | Description |
---|---|---|
params | Object[ ] | Certificate objects list. |
Certificate Object
Field | Type | Description |
---|---|---|
CN | String | Domain common name. |
creation | String | Creation date. |
domains | String[] | List of domains which the certificate is vaild for. |
expiration | String | Expiration date. |
dnstxt | Object[] | List of DNS TXT Records for each domains to validate if the certificate is not issued yet. |
file | String | It is the file name of the certificate, unique ID. |
issuer | String | Certified Authority signing the certificate. |
status | String | Status of the certificate.valid,the certificate is valid.about to expire, the certifiacte is about to expire.expired, the certificate is expired.not issued, the certificate is pendind to be issued.unknown, the certificate is not valid. |
type | String | LE Certificate. |
wildcard | String | true, the certificate is for wildcards domains. false, the certificate is for non wildcards domains. |
dnstxt Object
Field | Type | Description |
---|---|---|
domain | String | Domain name |
txt | String | DNS txt record LetsEncrypt must to validate. The DNS TXT record will be accesible by _acme-challenge.domain. |
Let's Encrypt SSL Wildcard Certificates
Let's Encrypt wildcard certificates are certificates valid only for wildcard domains.
Create a new Let's Encrypt Wildcard Certificate
Create a new Let's Encrypt Wildcard Certificate
Request example:
url -k -X POST -H 'Content-Type: application/json' -H "ZAPI_KEY: <ZAPI_KEY_STRING>"
-d '{"domains":["*.wildcard.test.relianoid.com"],"test":"true"}'
https://<relianoid_server>:444/api/v4.0/api.cgi/certificates/letsencryptz-wildcard
zcli certificate-le-wildcard create -wildcard true
POST /certificates/letsencryptz-wildcard
Create a new Let's Encrypt wildcard certificate.
Request parameters
Field | Type | Description | Required |
---|---|---|---|
domains | String[] | List of domains which the certificate is vaild for. | true |
test | String | true, the certificate is issued by LetsEncrypt Staging Server. false, the certificate is issued by LetsEncrypt Server and it will valid for Production environment. | true |
Response example:
{
"description" : "Create Let's Encrypt Wildcard certificate",
"params" : [
{
"CN" : "*.wildcard.test.relianoid.com",
"creation" : "",
"dnstxt" : [
{
"domain" : "*.wildcard.test.relianoid.com",
"txt" : "jtt2WBHXl0cRw33mgoHUo1hbFGLipNbeb2EtTWpRORM"
}
],
"domains" : [
"*.wildcard.test.relianoid.com"
],
"expiration" : "",
"file" : null,
"issuer" : "",
"status" : "not issued",
"type" : "LE Certificate",
"wildcard" : "true"
}
]
}
Response parameters
Field | Type | Description |
---|---|---|
params | Object[] | Certificate objects list. |
Certificate Object
Field | Type | Description |
---|---|---|
CN | String | Domain common name. |
creation | String | Creation date. |
dnstxt | Object[] | List of DNS TXT Records for each domains to validate if the certificate is not issued yet. |
domains | String[] | List of domains which the certificate is vaild for. |
expiration | String | Expiration date. |
file | String | It is the file name of the certificate, unique ID. |
issuer | String | Certified Authority signing the certificate. |
status | String | Status of the certificate.valid,the certificate is valid.about to expire, the certifiacte is about to expire.expired, the certificate is expired.not issued, the certificate is pendind to be issued.unknown, the certificate is not valid. |
type | String | LE Certificate. |
wildcard | String | true, the certificate is for wildcards domains. false, the certificate is for non wildcards domains. |
dnstxt Object
Field | Type | Description |
---|---|---|
domain | String | Domain name |
txt | String | DNS txt record LetsEncrypt must to validate. The DNS TXT record will be accesible by _acme-challenge.domain. |
Set an action in a Let's Encrypt Wildcard Certificate
Set an action in a Let's Encrypt Wildcard Certificate
Request example:
curl -k -X POST -H "ZAPI_KEY: <ZAPI_KEY_STRING>"
-d '{"action":"renew","force_renewal":"true","restart":"true"}'
https://<relianoid_server>:444/api/v4.0/api.cgi/certificates/letsencryptz-wildcard/*.example.domain.com/actions
zcli certificate-le-wildcard renew *.example.domain.com
POST /certificates/letsencryptz-wildcard/<domain>/actions
Apply an action to a Let's Encrypt certificate, see the Request parameters table for actions.
Request parameters
Field | Type | Description | Required |
---|---|---|---|
actions | String | The action to execute, the possibilities are: renew, the certificate will be renew; test the dns txt records will be checked via dns query. | |
force_renewal | String | (Only for "renew" action ) true, force the certificate to be renewed even it is not expired, false, the certificate will be renewed if it is due to be renewed ( less than 30 days to expire ). | |
restart | String | (Only for "renew" action ) true, all the farms using the certificate will be restarted. false, no farms using the certificate will be restarted. | |
dns | String | (Only for "test" action ) Dns server to be used to test the DNS TXT record _acme-challenge.domain. |
Response example:
{
"description" : "Let's Encrypt wildcard certificate actions",
"message" : "The action renew has been performed in Let's Encrypt certificate *.test1.wildcard.test.relianoid.io.",
"params" : {
"action" : "renew",
"status" : "valid"
}
}
Response parameters
Field | Type | Description |
---|---|---|
params | Object[ ] | Certificate objects list. |
Certificate Object
Field | Type | Description |
---|---|---|
action | String | Creation date. |
status | String | Status of the certificate.valid,the certificate is valid.about to expire, the certifiacte is about to expire.expired, the certificate is expired.not issued, the certificate is pendind to be issued.unknown, the certificate is not valid. |
dnstxt | Object[] | (Only for "test" action ) List of DNS TXT Records for each domains and their dns query results via a DNS server. |
dnstxt Object
Field | Type | Description |
---|---|---|
dns | String | DNS Server to be used. "blank" means use the configured in the system. |
domain | String | Domain name |
resource | Object | DNS resource to be checked. |
status | String | Result from checking DNS TXT Record via DNS server. down if DNS TXT re |
cord is not found DNS server. up if DNS TXT record is found.
resource Object
Field | Type | Description |
---|---|---|
rname | String | DNS resource name. Let's Encrypt requires _acme-challenge |
type | String | DNS record type. Let's Encrypt requires TXT |
rdata | String | DNS record value. |
Delete a wildcard Let's Encrypt Certificate
Delete a wildcard Let's Encrypt Certificate
Request example:
curl -k -X DELETE -H "ZAPI_KEY: <ZAPI_KEY_STRING>"
https://<relianoid_server>:444/api/v4.0/api.cgi/certificates/letsencryptz-wildcard/*.example.domain.com
zcli certificate-le-wildcard delete *.example.domain.com
DELETE /certificates/letsencryptz-wildcard/<domain>
Delete a Let's Encrypt wildcard certificate by domain.
Response example:
{
"description" : "Delete Let's Encrypt wildcard certificate",
"message" : "Let's Encrypt wildcard Certificate example.domain.com has been deleted.",
"success" : "true"
}
Let'sEncrypt SSL No Wildcard Certificates
Let'sEncrypt no wildcard certificates are certificates valid only for no wildcard domains.
Create a new Let'sEncrypt No Wildcard Certificate
Create a new Let's Encrypt No Wildcard Certificate
Request example:
curl -k -X POST -H 'Content-Type: application/json' -H "ZAPI_KEY: <ZAPI_KEY_STRING>"
-d '{"farmname":"lefarm","domains":["test.relianoid.com"],"test":"true","wildcard":"false"}'
https://<relianoid_server>:444/api/v4.0/api.cgi/certificates/letsencryptz
zcli certificate-le create -wildcard false
POST /certificates/letsencryptz
Create a new Let's Encrypt wildcard certificate.
Request parameters
Field | Type | Description | Required |
---|---|---|---|
farmname | String | Farm name which a temporal Service "Let's Encryptz" is configured in. | true if param vip is not sent. |
vip | String | IP of the system, where a temporal Farm "Let's Encryptz" is configured. | true if param farmname is not sent. |
domains | String[] | List of domains which the certificate is vaild for. | true |
wildcard | String | true, the certificate is for wildcards domains. false, the certificate is for non wildcards domains. | true |
test | String | true, the certificate is issued by LetsEncrypt Staging Server. false, the certificate is issued by LetsEncrypt Server and it will valid for Production environment. | true |
Response example:
{
"description" : "Create Let's Encrypt certificate",
"params" : {
"CN" : "test.relianoid.com",
"creation" : "May 31 11:05:30 2021 GMT",
"domains" : [
"test.relianoid.io"
],
"expiration" : "Aug 29 11:05:30 2021 GMT",
"file" : "/usr/local/relianoid/config/letsencrypt/live/test.relianoid.com/fullchain.pem",
"issuer" : "US,(STAGING) Let's Encrypt,(STAGING) Artificial Apricot R3",
"status" : "valid",
"type" : "LE Certificate",
"wildcard" : "false"
}
}
Response parameters
Field | Type | Description |
---|---|---|
params | Object[ ] | Certificate objects list. |
Certificate Object
Field | Type | Description |
---|---|---|
CN | String | Domain common name. |
creation | String | Creation date. |
domains | String[] | List of domains which the certifi### Response parameters |
If the are farms were been restarted, the warning field will describe it.
Field | Type | Description |
---|---|---|
params | Object[ ] | Certificate objects list. |
Certificate Object
Field | Type | Description |
---|---|---|
CN | String | Domain common name. |
creation | String | Creation date. |
domains | String[] | List of domains which the certificate is vaild for. |
expiration | String | Expiration date. |
file | String | It is the file name of the certificate, unique ID. |
issuer | String | Certified Authority signing the certificate. |
status | String | Status of the certificate.valid,the certificate is valid.about to expire, the certifiacte is about to expire.expired, the certificate is expired.not issued, the certificate is pendind to be issued.unknown, the certificate is not valid. |
type | String | LE Certificate. |
wildcard | String | true, the certificate is for wildcards domains. false, the certificate is for non wildcards domains. |
cate is vaild for. expiration | String | Expiration date. file | String | It is the file name of the certificate, unique ID. issuer | String | Certified Authority signing the certificate. status | String | Status of the certificate.valid,the certificate is valid.about to expire, the certifiacte is about to expire.expired, the certificate is expired.not issued, the certificate is pendind to be issued.unknown, the certificate is not valid. type | String | LE Certificate. wildcard | String | true, the certificate is for wildcards domains. false, the certificate is for non wildcards domains.
Show Certificate details in a Let's Encrypt No Wildcard Certificate
Show a Let's Encrypt No Wildcard Certificate details
Request example:
curl -k -X GET -H 'Content-Type: application/json' -H "ZAPI_KEY: zapi"
-d '{"autorenewal":"false","farmname":"Letsencryptfarm","force_renewal":"true","restart":"true"}'
https://192.168.103.200:444/api/v4.0/api.cgi/certificates/letsencryptz/test1.test.relianoid.io
GET /certificates/letsencryptz/<domain>/info
Show all the information included in a given Let's Encrypt No Wildcard certificate in the certificates store, including signatures, it is required the file name to refer.
Response example:
{
"description" : "Show Let's Encrypt certificate ce7.lab.relianoid.com",
"params" : {
"CN" : "ce7.lab.relianoid.com",
"autorenewal" : {
"farm" : null,
"force" : null,
"restart" : null,
"status" : "disabled",
"vip" : null
},
"creation" : "Dec 26 09:31:16 2023 GMT",
"domains" : [
"ce7.lab.relianoid.com"
],
"expiration" : "Mar 25 09:31:15 2024 GMT",
"file" : "/usr/local/relianoid/config/letsencrypt/live/ce7.lab.relianoid.com/fullchain.pem",
"issuer" : "US,(STAGING) Let's Encrypt,(STAGING) Ersatz Edamame E1",
"status" : "valid",
"type" : "LE Certificate",
"wildcard" : "false"
}
}
Response parameters
If the are farms were been restarted, the warning field will describe it.
Field | Type | Description |
---|---|---|
params | Object[ ] | Certificate objects list. |
Certificate Object
Field | Type | Description |
---|---|---|
CN | String | Domain common name. |
renewal | String[] | List of actions for the renewal order. |
creation | String | Creation date. |
domains | String[] | List of domains which the certificate is vaild for. |
expiration | String | Expiration date. |
file | String | It is the file name of the certificate, unique ID. |
issuer | String | Certified Authority signing the certificate. |
status | String | Status of the certificate.valid,the certificate is valid.about to expire, the certifiacte is about to expire.expired, the certificate is expired.not issued, the certificate is pendind to be issued.unknown, the certificate is not valid. |
type | String | LE Certificate. |
wildcard | String | true, the certificate is for wildcards domains. false, the certificate is for non wildcards domains. |
Set an action in a Let's Encrypt no Wildcard Certificate
Set an action in a Let's Encrypt No Wildcard Certificate
Request example:
curl -k -X POST -H "ZAPI_KEY: <ZAPI_KEY_STRING>"
-d '{"action":"renew","vip":"192.168.101.44","force_renewal":"true","restart":"true"}'
https://<relianoid_server>:444/api/v4.0/api.cgi/certificates/letsencryptz/example.domain.com/actions
zcli certificate-le renew example.domain.com ( not implemented )
POST /certificates/letsencryptz/<domain>/actions
Set an action in a Let's Encrypt no wildcard certificate, see the Request parameters table for actions.
Request parameters
Field | Type | Description | Required |
---|---|---|---|
action | String | The action to execute: the possibilities are: renew, the certificatewill be renewed. | |
farmname | String | Farm name which a temporal Service "Let's Encryptz" is configured in to renew the certificate. | true if param vip is not sent. |
vip | String | IP of the system, where a temporal Farm "Let's Encryptz" is configuredi to renew the certificate. | true if param farmname is not sent. |
force_renewal | String | true, force the certificate to be renewed even it is not expired, false, the certificate will be renewed if it is due to be renewed ( less than 30 days to expire ). | |
restart | String | true, all the farms using the certificate will be restarted. false, no farms using the certificate will be restarted. |
Response example:
{
"description" : "Let's Encrypt certificate actions",
"params" : {
"CN" : "test.relianoid.com",
"creation" : "May 31 11:35:08 2021 GMT",
"domains" : [
"test.relianoid.com"
],
"expiration" : "Aug 29 11:35:08 2021 GMT",
"file" : "/usr/local/relianoid/config/letsencrypt/live/test.relianoid.com/fullchain.pem",
"issuer" : "US,(STAGING) Let's Encrypt,(STAGING) Artificial Apricot R3",
"status" : "valid",
"type" : "LE Certificate",
"wildcard" : "false"
},
"warning" : "The following farms were been restarted: testl7farm"
}
Response parameters
If the are farms were been restarted, the warning field will describe it.
Field | Type | Description |
---|---|---|
params | Object[ ] | Certificate objects list. |
Certificate Object
Field | Type | Description |
---|---|---|
CN | String | Domain common name. |
creation | String | Creation date. |
domains | String[] | List of domains which the certificate is vaild for. |
expiration | String | Expiration date. |
file | String | It is the file name of the certificate, unique ID. |
issuer | String | Certified Authority signing the certificate. |
status | String | Status of the certificate.valid,the certificate is valid.about to expire, the certifiacte is about to expire.expired, the certificate is expired.not issued, the certificate is pendind to be issued.unknown, the certificate is not valid. |
type | String | LE Certificate. |
wildcard | String | true, the certificate is for wildcards domains. false, the certificate is for non wildcards domains. |
Delete a no wildcard Let's Encrypt Certificate
Delete a no wildcard Let's Encrypt Certificate
Request example:
curl -k -X DELETE -H "ZAPI_KEY: <ZAPI_KEY_STRING>"
https://<relianoid_server>:444/api/v4.0/api.cgi/certificates/letsencryptz/example.domain.com
zcli certificate-le delete example.domain.com
DELETE /certificates/letsencryptz/<domain>
Delete a Let's Encrypt certificate by domain.
Response example:
{
"description" : "Delete Let's Encrypt certificate",
"message" : "Let's Encrypt Certificate example.domain.com has been deleted.",
"success" : "true"
}
Farms
RELIANOID 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 RELIANOID ADC.
- LSLB: This module can work with http and l4xnat profile farms. It works as a web reverse proxy or router
- GSLB: This module can work with gslb profile farm. It works as Domain Name Server
- DSLB: This module can work with datalink profile farm. It works as a gateway.
List a summary of farms
List a summary farms
Request example:
curl -k -X GET -H "ZAPI_KEY: <ZAPI_KEY_STRING>"
https://<relianoid_server>:444/api/v4.0/api.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://<relianoid_server>:444/api/v4.0/api.cgi/farms
zcli farm list
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 in maintenance mode; problem, the farm is up and there are some backends that are unreachable, but at least one backend has the "up" status; maintenance, the farm is up and there are backends in up status, but at least 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://<relianoid_server>:444/api/v4.0/api.cgi/farms/FarmHTTP
zcli farm delete 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://<relianoid_server>:444/api/v4.0/api.cgi/farms/FarmTCP/actions
zcli farm stop FarmTCP
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.
Get the Farm status
Get the status of a Farm
Request example:
curl -k -X PUT -H 'Content-Type: application/json' -H "ZAPI_KEY: <ZAPI_KEY_STRING>"
-d '{"action":"stop"}' https://<relianoid_server>:444/api/v4.0/api.cgi/farms/Farm/status
zcli farm-status get Farm
GET /farms/<farmname>/status
Get the status of a Farm
Response example:
{
"info" : "Show farm Farm status",
"params" : [
{
"status" : "stop"
}
]
}
Response parameters
The response will be a JSON object with a key set to params.
Params:
Field | Type | Description |
---|---|---|
status | String | The status of the farm. This can be: up, down, maintenence, critical or needed-restart. |
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://<relianoid_server>:444/api/v4.0/api.cgi/farms/httpFarm
zcli farm get 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
}
],
"addresponseheader" : [
{
"header" : "Session: 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",
"errorWAF" : "The request was rejected by the server.",
"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",
"removeresponseheader" : [
{
"id" : 0,
"pattern" : "Host"
}
],
"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" : "",
"pinnedconnection" : 0,
"routingpolicy" : "ROUND_ROBIN"
},
{
"backends" : [
{
"alias" : "http-server",
"id" : 0,
"ip" : "192.168.0.168",
"port" : 80,
"status" : "up",
"timeout" : null,
"weight" : null,
"priority" : 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" : "",
"pinnedconnection" : 0,
"routingpolicy" : "ROUND_ROBIN"
},
]
}
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 client request. |
addresponseheader (from 4.0.1) | Object[] | It is a list of objects with the headers to add to the backend response. |
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 aessslhwoffloading, 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. |
errorWAF | String | Personalized message for responding when WAF rejects a request (from 4.0.2). |
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. optionsHTTP (from 4.0.1), add the OPTIONS verb to the previous ones. 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. |
removeresponseheader (from 4.0.1) | Object[] | It is a list of regular expressions to remove headers from the backend response. The removed headers will not reach the client. |
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 | Object[] | 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. From 4.0.2 new options availables: enabled-path and enabled-backends-path. the path applies if the RewriteUrl directive modified the request URL. This flag forces to revert the URL transformation that RewriteUrl did. |
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 in maintenance mode; problem, the farm is up and there are some backends that are unreachable, but at least one backend has the "up" status; maintenance, the farm is up and there are backends in up status, but at least 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. |
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. |
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. |
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. |
+ in EE version:
Field | Type | Description |
---|---|---|
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. |
redirect_code | Number | It is the HTTP code returned when a redirect is configurated. The possible values are 301, 302, 307, |
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. |
pinnedconnection (from version 4.0.2) | Number | Specify if we want to pin all the connections, (default: 0, no pinned). If Pinnedconnection is set to 1, zproxy directly forwards all data without parsing or editing. |
routingpolicy (from version 4.0.2) | String | Specify the routing policy. All the algorithms are weighted with all the weights set in each backend. There is four options: ROUND_ROBIN use the round robin algorithm as a routing policy (default). LEAST_CONNECTIONS select the backend with least connections established using as a proportion the weights set. RESPONSE_TIME select the backend with the lowest response time using as a proportion the weights set. PENDING_CONNECTIONS select the backend with least pending connections using as a proportion the weights set. |
rewriteurl (from version 4.0.2) | Object[] | It checks a pattern in order to get strings from URL and replace them. Several RewriteUrl directives can be added. All of them will be sequentially applied to the incoming URL unless the last flag is set that will finish the rewrite url phase. |
Backend object for HTTP farms:
Field | Type | Description |
---|---|---|
id | Number | Backend identifier inside the given service. |
ip | String | Backend's IP where the real service is running. |
port | Number | Backend's port where the real service is running. |
status | String | Backend status. The possible values are: up, the farm is running and the backend is ready to receive connections; down, the farm is running and the service has detected that the backend is not working; maintenance, backend is marked as not ready for receiving connections by the administrator, this option is useful for backend's 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. |
priority (from 4.0.1) | Number | The priority value for the current real server (accepted values are 1 or 2). Lower values have more priority and the default value is 1, so the backend will be used anytime it is available. If all backends with priority 1 are down or in maintenance, the backend with priority 2 is enabled to maintain the service available. Only one backend with priority 2 is allowed currently. |
+ in EE version:
Field | Type | Description |
---|---|---|
alias | String | It is a nick to help to identify the backend. Alias |
connection_limit (from 4.0.2) | Number | The maximum number of established connection per backend. With a value of 0, there will not be a limit in the backend. The client will receive a 503 error if there aren't available backends. |
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://<relianoid_server>:444/api/v4.0/api.cgi/farms
zcli farm create -farmname newHTTPfarm -profile http -vip 192.168.100.23 -vport 80
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 |
+ in EE version:
Field | Type | Description |
---|---|---|
copy_from (from 4.0.1) | String | This parameter expects the name of a farm that exists. If this parameter is sent, the farm is copied from the farm specified in it. The farmname, vip and vport values will be overwritten. |
Response example (param 'interface' only in EE version):
{
"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", "errorWAF":"Message error WAF",
"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://<relianoid_server>:444/api/v4.0/api.cgi/farms/FarmHTTP
zcli farm set FarmHTTP -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 -errorcode414 'Message error 414' -logs true
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. optionsHTTP (from 4.0.1), add the OPTIONS verb to the previous ones. 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. |
error414 | String | Personalized message error 414. |
error500 | String | Personalized message error 500. |
error501 | String | Personalized message error 501. |
error503 | String | Personalized message error 503. |
listener | String | A listener defines how the farm is going to play with the requests from the clients. The options are: http for not secured protocol or https for secured protocol. |
ciphers | String | Only in listener with https value. Used to build a list of ciphers accepted by SSL connections in order to harden the SSL connection. The options are: all, all the ciphers will be accepted; highsecurity, only ciphers for high security will be accepted; customsecurity, only ciphers loaded in cipherc field will be accepted; or aessslhwoffloading, 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. |
+ in EE version:
Field | Type | Description |
---|---|---|
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. |
errorWAF | String | Personalized message error WAF (from version 4.0.2). |
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. |
certname | String | Https certificate configured |
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",
"errorWAF" : "Message error WAF",
"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 a Custom Header to the Request
Add a Custom Header to the Request
Request example:
curl -k -X POST -H 'Content-Type: application/json' -H "ZAPI_KEY: <ZAPI_KEY_STRING>"
-d '{"header":"loadbalancer: true"}' https://<relianoid_server>:444/api/v4.0/api.cgi/farms/MyHttpFarm/addheader
zcli farm-add-request-header MyHttpFarm -header "loadbalancer: true"
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"
}
Modify an add a Custom Header to the Request rule
Modify an add a Custom Header to the Request rule
Request example:
curl -k -X PUT -H 'Content-Type: application/json' -H "ZAPI_KEY: <ZAPI_KEY_STRING>"
-d '{"header":"loadbalancer: true"}' https://<relianoid_server>:444/api/v4.0/api.cgi/farms/MyHttpFarm/addheader/id
zcli farm-add-request-header MyHttpFarm -header "loadbalancer: true"
PUT /farms/<farmname>/addheader/<id>
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" : "Modify an addheader directive.",
"message" : "Modified an item from the addheader list",
"success" : "true"
}
Delete a Custom Header from the Request
Request example:
curl -k -X DELETE -H "ZAPI_KEY: <ZAPI_KEY_STRING>"
https://<relianoid_server>:444/api/v4.0/api.cgi/farms/MyHttpFarm/addheader/0
zcli farm-add-request-header remove MyHttpFarm 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 Rule to Remove Headers from the Request
Add Rule to Remove Headers from the Request
Request example:
curl -k -X POST -H 'Content-Type: application/json' -H "ZAPI_KEY: <ZAPI_KEY_STRING>"
-d '{"pattern":"^client:"}' https://<relianoid_server>:444/api/v4.0/api.cgi/farms/MyHttpFarm/headremove
zcli farm-remove-request-header add MyHttpFarm -pattern "^client:"
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"
}
Modify a Remove Headers from the Request rule
Modify a Remove Headers from the Request rule
Request example:
curl -k -X PUT -H 'Content-Type: application/json' -H "ZAPI_KEY: <ZAPI_KEY_STRING>"
-d '{"pattern":"^client:"}' https://<relianoid_server>:444/api/v4.0/api.cgi/farms/MyHttpFarm/headremove/id
zcli farm-remove-request-header add MyHttpFarm -pattern "^client:"
PUT /farms/<farmname>/headremove/<id>
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" : "Modify an headremove directive.",
"message" : "Modified an item from the headremove list",
"success" : "true"
}
Delete a Rule to Remove Headers from the Request
Delete a Rule to Remove Headers from the Request
Request example:
curl -k -X DELETE -H "ZAPI_KEY: <ZAPI_KEY_STRING>"
https://<relianoid_server>:444/api/v4.0/api.cgi/farms/MyHttpFarm/headremove/0
zcli farm-remove-request-header remove MyHttpFarm 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 Custom Header to the Response
Add a Custom Header to the Response
Request example:
curl -k -X POST -H 'Content-Type: application/json' -H "ZAPI_KEY: <ZAPI_KEY_STRING>"
-d '{"header":"loadbalancer: true"}' https://<relianoid_server>:444/api/v4.0/api.cgi/farms/MyHttpFarm/addresponseheader
zcli farm-add-response-header add MyHttpFarm -header loadbalancer:true
This call is available from version 4.0.2
POST /farms/<farmname>/addresponseheader
The farm will add the header to the backend response.
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 a header to the backend repsonse.",
"message" : "Added a new header to the backend response",
"status" : "needed restart",
"success" : "true"
}
Modify an add a Custom Header to the Response rule
Modify an add a Custom Header to the Response rule
Request example:
curl -k -X PUT -H 'Content-Type: application/json' -H "ZAPI_KEY: <ZAPI_KEY_STRING>"
-d '{"header":"loadbalancer: true"}' https://<relianoid_server>:444/api/v4.0/api.cgi/farms/MyHttpFarm/addresponseheader/id
zcli farm-add-response-header add MyHttpFarm -header loadbalancer:true
This call is available from version 4.0.2
PUT /farms/<farmname>/addresponseheader/<id>
The farm will add the header to the backend response.
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" : "Modify an addresponseheader directive.",
"message" : "Modified an item from the addresponseheader list",
"success" : "true"
}
Delete a Custom Header from the Response
Delete a Custom Header from the Response
Request example:
curl -k -X DELETE -H "ZAPI_KEY: <ZAPI_KEY_STRING>"
https://<relianoid_server>:444/api/v4.0/api.cgi/farms/MyHttpFarm/addresponseheader/0
zcli farm-add-response-header remove torta 0
This call is available from version 4.0.2
DELETE /farms/<farmname>/addresponseheader/<index>
index is the index of the addresponseheader array to delete.
Response example:
{
"description" : "Delete a header previously added to the backend response.",
"message" : "The header 0 was deleted successfully",
"status" : "needed restart",
"success" : "true"
}
Add a Rule to Remove Headers from Response
Add a Rule to Remove Headers from Response
Request example:
curl -k -X POST -H 'Content-Type: application/json' -H "ZAPI_KEY: <ZAPI_KEY_STRING>"
-d '{"pattern":"^client:"}' https://<relianoid_server>:444/api/v4.0/api.cgi/farms/MyHttpFarm/removeresponseheader
zcli farm-remove-response-header add MyHttpFarm -pattern "^client:"
This call is available from version 4.0.2
POST /farms/<farmname>/removeresponseheader
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" : "Remove a header from the backend response.",
"message" : "Added a patter to remove reponse headers",
"status" : "needed restart",
"success" : "true"
}
Modify a Remove Headers from Response rule
Modify a Remove Headers from Response rule
Request example:
curl -k -X PUT -H 'Content-Type: application/json' -H "ZAPI_KEY: <ZAPI_KEY_STRING>"
-d '{"pattern":"^client:"}' https://<relianoid_server>:444/api/v4.0/api.cgi/farms/MyHttpFarm/removeresponseheader/id
zcli farm-remove-response-header add MyHttpFarm -pattern "^client:"
This call is available from version 4.0.2
PUT /farms/<farmname>/removeresponseheader/<id>
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" : "Modify a remove response header directive.",
"message" : "Modified an item from the removeresponseheader list",
"success" : "true"
}
Delete a Rule to Remove Header from Response
Delete a Rule to Remove Header from Response
Request example:
curl -k -X DELETE -H "ZAPI_KEY: <ZAPI_KEY_STRING>"
https://<relianoid_server>:444/api/v4.0/api.cgi/farms/MyHttpFarm/removeresponseheader/0
zcli farm-remove-response-header remove torta 0
This call is available from version 4.0.2
DELETE /farms/<farmname>/removeresponseheader/<index>
index is the index of the removeresponseheader array to delete.
Response example:
{
"description" : "Delete a pattern to remove response headers.",
"message" : "The pattern 0 was deleted successfully",
"status" : "needed restart",
"success" : "true"
}
Add a Rule to Rewrite Headers from Request
Add a Rule to Rewrite Headers from Request
Request example:
curl -k -X POST -H 'Content-Type: application/json' -H "ZAPI_KEY: <ZAPI_KEY_STRING>"
-d '{"header":"^Cookie:","match":"^COOKIESESSION=(.*)","replace":"COOKIEUSER=$1"}'
https://<relianoid_server>:444/api/v4.0/api.cgi/farms/MyHttpFarm/replacerequestheader
farm-replace-request-header add farm1 -header ^Cookie: -match ^COOKIESESSION=(.*) -replace COOKIEUSER=$1`
This call is available from version 4.0.2
POST /farms/<farmname>/replacerequestheader
Add rules to rewrite headers from the request.
Request parameters
Field | Type | Description | Required |
---|---|---|---|
header | String | Regex with the header name to be rewrited | true |
match | String | Regex value to match what we want to replace | true |
replace | String | Value to replace matches | true |
Response example:
{
"description" : "Add a Replace Header.",
"message" : "Added a new replace header",
"status" : "needed restart",
"success" : "true"
}
Modify a Rewrite Headers from Request rule
Modify a Rewrite Headers from Request rule
Request example:
curl -k -X POST -H 'Content-Type: application/json' -H "ZAPI_KEY: <ZAPI_KEY_STRING>"
-d '{"header":"^Cookie:","match":"^COOKIESESSION=(.*)","replace":"COOKIEUSER=$1"}'
https://<relianoid_server>:444/api/v4.0/api.cgi/farms/MyHttpFarm/replacerequestheader/id
farm-replace-request-header add farm1 -header ^Cookie: -match ^COOKIESESSION=(.*) -replace COOKIEUSER=$1`
This call is available from version 4.0.2
PUT /farms/<farmname>/replacerequestheader/<id>
Add rules to rewrite headers from the request.
Request parameters
Field | Type | Description | Required |
---|---|---|---|
header | String | Regex with the header name to be rewrited | true |
match | String | Regex value to match what we want to replace | true |
replace | String | Value to replace matches | true |
Response example:
{
"description" : "Modify a replaceHeader directive.",
"message" : "Modified an item from the replaceHeader list",
"success" : "true"
}
Delete a Rule to Rewrite Headers from Request
Delete a Rule to Rewrite Headers from Request
Request example:
curl -k -X DELETE -H "ZAPI_KEY: <ZAPI_KEY_STRING>"
https://<relianoid_server>:444/api/v4.0/api.cgi/farms/MyHttpFarm/replacerequestheader/0
zcli farm-replace-request-header remove MyHttpFarm 0
This call is available from version 4.0.2
DELETE /farms/<farmname>/replacerequestheader/<index>
index is the index of the replacerequestheader array to delete.
Response example:
{
"description" : "Delete a replace header directive.",
"message" : "The replace header 0 was deleted successfully",
"status" : "needed restart",
"success" : "true"
}
Move a Rewrite Headers from Request rule
Move a Rewrite Headers from Request rule
Request example:
curl -k -X POST -H 'Content-Type: application/json' -H "ZAPI_KEY: <ZAPI_KEY_STRING>"
-d '{"position":1}'
https://<relianoid_server>:444/api/v4.0/api.cgi/farms/MyHttpFarm/replacerequestheader/id/actions
farm-replace-request-header add farm1 -header ^Cookie: -match ^COOKIESESSION=(.*) -replace COOKIEUSER=$1`
This call is available from version 4.0.2
POST /farms/<farmname>/replacerequestheader/<id>/actions
Move a ReplaceRequest Header.
Request parameters
Field | Type | Description | Required |
---|---|---|---|
position | Number | New rule position | true |
Response example:
{
"description" : "Move a replace header directive",
"message" : "Header was moved successfully.",
"params" : {
"position" : "1"
}
}
Add a Rule to Rewrite Headers from Response
Add a Rule to Rewrite Headers from Response
Request example:
curl -k -X POST -H 'Content-Type: application/json' -H "ZAPI_KEY: <ZAPI_KEY_STRING>"
-d '{"header":"^Cookie:","match":"^COOKIESESSION=(.*)","replace":"COOKIEUSER=$1"}'
https://<relianoid_server>:444/api/v4.0/api.cgi/farms/MyHttpFarm/replaceresponseheader
farm-replace-response-header add farm1 -header ^Cookie: -match ^COOKIESESSION=(.*) -replace COOKIEUSER=$1` -t$
This call is available from version 4.0.2
POST /farms/<farmname>/replaceresponseheader
Add rules to rewrite headers from the response.
Request parameters
Field | Type | Description | Required |
---|---|---|---|
header | String | Regex with the header name to be rewrited | true |
match | String | Regex value to match what we want to replace | true |
replace | String | Value to replace matches | true |
Response example:
{
"description" : "Add a Replace Header.",
"message" : "Added a new replace header",
"status" : "needed restart",
"success" : "true"
}
Modify a Rewrite Headers from Response rule
Modify a Rewrite Headers from Response rule
Request example:
curl -k -X POST -H 'Content-Type: application/json' -H "ZAPI_KEY: <ZAPI_KEY_STRING>"
-d '{"header":"^Cookie:","match":"^COOKIESESSION=(.*)","replace":"COOKIEUSER=$1"}'
https://<relianoid_server>:444/api/v4.0/api.cgi/farms/MyHttpFarm/replaceresponseheader/id
farm-replace-response-header add farm1 -header ^Cookie: -match ^COOKIESESSION=(.*) -replace COOKIEUSER=$1` -t$
This call is available from version 4.0.2
PUT /farms/<farmname>/replaceresponseheader/<id>
Add rules to rewrite headers from the response.
Request parameters
Field | Type | Description | Required |
---|---|---|---|
header | String | Regex with the header name to be rewrited | true |
match | String | Regex value to match what we want to replace | true |
replace | String | Value to replace matches | true |
Response example:
{
"description" : "Modify a replaceHeader directive.",
"message" : "Modified an item from the replaceHeader list",
"success" : "true"
}
Delete a Rule to Rewrite Headers from Response
Delete a Rule to Rewrite Headers from Response
Request example:
curl -k -X DELETE -H "ZAPI_KEY: <ZAPI_KEY_STRING>"
https://<relianoid_server>:444/api/v4.0/api.cgi/farms/MyHttpFarm/replaceresponseheader/0
zcli farm-replace-response-header remove MyHttpFarm 0
This call is available from version 4.0.2
DELETE /farms/<farmname>/replaceresponseheader/<index>
index is the index of the replaceresponseheader array to delete.
Response example:
{
"description" : "Delete a replace header directive.",
"message" : "The replace header 0 was deleted successfully",
"status" : "needed restart",
"success" : "true"
}
Move a Rewrite Headers from Request rule
Move a Rewrite Headers from Response rule
Request example:
curl -k -X POST -H 'Content-Type: application/json' -H "ZAPI_KEY: <ZAPI_KEY_STRING>"
-d '{"position":1}'
https://<relianoid_server>:444/api/v4.0/api.cgi/farms/MyHttpFarm/replaceresponseheader/id/actions
farm-replace-response-header add farm1 -header ^Cookie: -match ^COOKIESESSION=(.*) -replace COOKIEUSER=$1`
This call is available from version 4.0.2
POST /farms/<farmname>/replaceresponseheader/<id>/actions
Move a ReplaceRequest Header.
Request parameters
Field | Type | Description | Required |
---|---|---|---|
position | Number | New rule position | true |
Response example:
{
"description" : "Move a replace header directive",
"message" : "Header was moved successfully.",
"params" : {
"position" : "1"
}
}
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://<relianoid_server>:444/api/v4.0/api.cgi/farms/httpFarm/certificates
zcli farm-certificate add httpFarm -file example.pem
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://<relianoid_server>:444/api/v4.0/api.cgi/farms/newfarm/certificates/certif.pem/actions
zcli farm-certificate move newfarm zertif.pem -position 0
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://<relianoid_server>:444/api/v4.0/api.cgi/farms/MyHttpFarm/certificates/example.pem
zcli farm-certificate remove MyHttpFarm 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://<relianoid_server>:444/api/v4.0/api.cgi/farms/httpFarm/ipds/blacklists
zcli farm-blacklist add httpFarm -name china
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://<relianoid_server>:444/api/v4.0/api.cgi/ipds/waf/test_waf_ori/rules/0/actions
zcli farm-waf move httpFarm REQUEST-901-INITIALIZATION -position 2
POST /farms/<farmname>/ipds/<waf|blacklists>/<name>/actions
The move IPDS rules are only available for WAF and Blacklist rules. In this kind of rules is important the order that is going to be checked.
The name
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 IPDS rule 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://<relianoid_server>:444/api/v4.0/api.cgi/farms/httpFarm/ipds/blacklists/china
zcli farm-blacklist remove httpFarm 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://<relianoid_server>:444/api/v4.0/api.cgi/farms/cookiefarm/services/serv
zcli farm get cookiefarm -filter services
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,
"priority" : null,
"connection_limit" : null
},
{
"alias" : "http-server",
"id" : 0,
"ip" : "192.168.100.254",
"port" : 80,
"status" : "up",
"timeout" : null,
"weight" : null,
"priority" : null,
"connection_limit" : null
}
],
"cookiedomain" : "relianoid.cpm",
"cookieinsert" : "true",
"cookiename" : "my-cookie-name",
"cookiepath" : "/path",
"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" : "",
"pinnedconnection" : 0,
"routingpolicy" : "ROUND_ROBIN",
"replacerequestheader" : [],
"replaceresponseheader" : [],
"addrequestheader" : [],
"addresponseheader" : [],
"removerequestheader" : [],
"removeresponseheader" : [],
"rewriteurl" : [],
"sessions" : []
}
}
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. |
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. |
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. |
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. |
pinnedconnection (from version 4.0.2) | Number | Specify if we want to pin all the connections, (default: 0, no pinned). If Pinnedconnection is set to 1, zproxy directly forwards all data without parsing or editing. |
routingpolicy (from version 4.0.2) | String | Specify the routing policy. All the algorithms are weighted with all the weights set in each backend. There is four options: ROUND_ROBIN use the round robin algorithm as a routing policy (default). LEAST_CONNECTIONS select the backend with least connections established using as a proportion the weights set. RESPONSE_TIME select the backend with the lowest response time using as a proportion the weights set. PENDING_CONNECTIONS select the backend with least pending connections using as a proportion the weights set. |
+ in EE version:
Field | Type | Description |
---|---|---|
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. |
redirect_code | Number | It is the HTTP code returned when a redirect is configurated. The possible values are 301, 302, 307. |
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. |
replacerequestheader (from version 4.0.2) | Object[] | Array of rules to replace a header in request. If several regex matches in the header, only the first one will apply. The replaceHeader directive in the services has priority over the listener one. |
replaceresponseheader (from version 4.0.2) | Object[] | Array of rules to replace a header in response. If several regex matches in the header, only the first one will apply. The replaceHeader directive in the services has priority over the listener one. |
addrequestheader (from version 4.0.2) | Object[] | Array of rules to Add the defined header to the request passed to the clients. The header is added verbatim. |
addresponseheader (from version 4.0.2) | Object[] | Array of rules to Add the defined header to the response passed to the clients. The header is added verbatim. |
removerequestheader (from version 4.0.2) | Object[] | Array of rules to Remove certain headers from the outcomming request, the header sent by the backend is not sent to the client. |
removeresponseheader (from version 4.0.2) | Object[] | Array of rules to Remove certain headers from the outcomming response, the header sent by the backend is not sent to the client. |
rewriteurl (from version 4.0.2) | Object[] | Array of rules to Changes the Location and Content-Location headers in the responses to show the virtual host that was sent in the request. |
sessions (from version 4.0.2) | Object[] | List of static and dynamic sessions created for this farm service. |
Backend object for HTTP farms:
Field | Type | Description |
---|---|---|
id | Number | Backend identifier inside the given service. |
ip | String | Backend's IP where the real service is running. |
port | Number | Backend's port where the real service is running. |
status | String | Backend status. The possible values are: up, the farm is running and the backend is ready to receive connections; down, the farm is running and the service has detected that the backend is not working; maintenance, backend is marked as not ready for receiving connections by the administrator, this option is useful for backend's 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. |
priority (from 4.0.1) | Number | The priority value for the current real server (accepted values are 1 or 2). Lower values have more priority and the default value is 1, so the backend will be used anytime it is available. If all backends with priority 1 are down or in maintenance, the backend with priority 2 is enabled to maintain the service available. Only one backend with priority 2 is allowed currently. |
+ in EE version:
Field | Type | Description |
---|---|---|
alias | String | It is a nick to help to identify the backend. Alias |
connection_limit (from 4.0.2) | Number | The maximum number of established connection per backend. With a value of 0, there will not be a limit in the backend. The client will receive a 503 error if there aren't available backends. |
replaceRequestHeader and replaceResponseHeader objects for HTTP farm services:
Field | Type | Description |
---|---|---|
header | String | Regex with the header name to be rewrited. |
match | String | Regex value to match what we want to replace. |
replace | String | Value to replace matches. |
addRequestHeader and addResponseHeader object for HTTP farm services:
Field | Type | Description |
---|---|---|
header | String | Regex with the header name to be rewrited. |
removeRequestHeader and removeResponseHeader object for HTTP farm services:
Field | Type | Description |
---|---|---|
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. |
rewriteUrl object for HTTP farm services:
Field | Type | Description |
---|---|---|
pattern | String | It is a string with a regexp to look for in the url. If url matches in the pattern, the matched text will be replaced. |
replace | String | It is a string to replace the matched text. |
last | String | True or False. If true is set, that will finish the rewrite url phase. |
session object for HTTP farm services:
Field | Type | Description |
---|---|---|
id | Number | Backend ID which will receive the connection. |
session | String | It is the session identifier or a connection, its value depend on the persistence parameter of the farm. If persistence is 'IP' session should be a IPv4 or IPv6, e.g. 192.168.42.65; |
type | String | There are two type of sessions: dynamic is a connection that load balancer pins with a backend using the farm load balancing algorithm; static is a connection that the load balancer administrator pins with a backend. The static sessions will not be redirect to another backend if its backed in unreachable. |
ttl | String | It is a string with the session time to expire. The ttl value will be null if the session is not of type static. |
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://<relianoid_server>:444/api/v4.0/api.cgi/farms/FarmHTTP/services
zcli farm-service add FarmHTTP -id newserv
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","pinnedconnection":0,"routingpolicy":"ROUND_ROBIN"}' https://<relianoid_server>:444/api/v4.0/api.cgi/farms/FarmHTTP/services/sev2
zcli farm-service set farmHTTP sev2 -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 -pinnedconnection 0 -routingpolicy ROUND_ROBIN
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. |
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. |
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. |
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. |
pinnedconnection (from version 4.0.2) | Number | Specify if we want to pin all the connections, (default: 0, no pinned). If Pinnedconnection is set to 1, zproxy directly forwards all data without parsing or editing. |
routingpolicy (from version 4.0.2) | String | Specify the routing policy. All the algorithms are weighted with all the weights set in each backend. There is four options: ROUND_ROBIN use the round robin algorithm as a routing policy (default). LEAST_CONNECTIONS select the backend with least connections established using as a proportion the weights set. RESPONSE_TIME select the backend with the lowest response time using as a proportion the weights set. PENDING_CONNECTIONS select the backend with least pending connections using as a proportion the weights set. |
+ in EE version:
Field | Type | Description |
---|---|---|
redirect_code | Number | It is the HTTP code returned when a redirect is configurated. The possible values are 301, 302, 307, |
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. |
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. |
rewritelocation (from version 4.0.2) | 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. Other options availables: enabled-path and enabled-backends-path. the path applies if the RewriteUrl directive modified the request URL. This flag forces to revert the URL transformation that RewriteUrl did. |
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",
"pinnedconnection" : 0,
"routingpolicy" : "ROUND_ROBIN"
},
"status" : "needed restart"
}
Response Parameters
The response will be a JSON with requested parameters updated and the status field with the current status of the farm. If Restart action needs to be taken to apply the changes of the farm, the value will be needed restart.
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://<relianoid_server>:444/api/v4.0/api.cgi/farms/FarmHTTP/services/service1/fg
zcli farm-service-farmguardian add FarmHTTP service1 -name check_tcp-cut_conns
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",
"status": "up"
}
Remove FarmGuardian
Remove FarmGuardian
Request example:
curl -k -X DELETE -H "ZAPI_KEY: <ZAPI_KEY_STRING>"
https://<relianoid_server>:444/api/v4.0/api.cgi/farms/FarmHTTP/service/service1/fg/check_tcp-cut_conns
zcli farm-service-farmguardian remove FarmHTTP service1 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",
"status": "up"
}
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://<relianoid_server>:444/api/v4.0/api.cgi/farms/FarmHTTP/services/service1/actions
zcli farm-service move FarmHTTP service1 -position 0
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://<relianoid_server>:444/api/v4.0/api.cgi/farms/FarmHTTP/services/service1
zcli farm-service remove FarmHTTP 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"
}
Add a Rule to Rewrite Headers from Request
Add a Rule to Rewrite Headers from Request
Request example:
curl -k -X POST -H 'Content-Type: application/json' -H "ZAPI_KEY: <ZAPI_KEY_STRING>"
-d '{"header":"^Cookie:", "match":"^COOKIESESSION=(.*)", "replace":"COOKIEUSER=$1`"}'
https://<relianoid_server>:444/api/v4.0/api.cgi/farms/MyHttpFarm/services/MyService/replacerequestheader
zcli farm-service-replacerequestheader add farm1 -header "^Cookie:" -match "^COOKIESESSION=(.*)" -replace "COOKIEUSER=$1`"
This call is available from version 4.0.2
POST /farms/<farmname>/service/<servicename>/replacerequestheader
Add rules to rewrite headers from the request.
Request parameters
Field | Type | Description | Required |
---|---|---|---|
header | String | Regex with the header name to be rewrited | true |
match | String | Regex value to match what we want to replace | true |
replace | String | Value to replace matches | true |
Response example:
{
"description" : "Add a Replace Header.",
"message" : "Added a new replace header"
}
Modify a Rewrite Headers from Request rule
Modify a Rewrite Headers from Request rule
Request example:
curl -k -X PUT -H 'Content-Type: application/json' -H "ZAPI_KEY: <ZAPI_KEY_STRING>"
-d '{"header":"^Cookie:", "match":"^COOKIESESSION=(.*)", "replace":"COOKIEUSER=$1`"}'
https://<relianoid_server>:444/api/v4.0/api.cgi/farms/MyHttpFarm/services/MyService/replacerequestheader/id
zcli farm-service-replacerequestheader add farm1 -header "^Cookie:" -match "^COOKIESESSION=(.*)" -replace "COOKIEUSER=$1`"
This call is available from version 4.0.2
PUT /farms/<farmname>/service/<servicename>/replacerequestheader/<id>
Modify a rule of rewrite headers from the request.
Request parameters
Field | Type | Description | Required |
---|---|---|---|
header | String | Regex with the header name to be rewrited | true |
match | String | Regex value to match what we want to replace | true |
replace | String | Value to replace matches | true |
Response example:
{
"description" : "Modify replaceHeader directive.",
"message" : "Modified an item from the ReplaceHeader list",
"success" : "true"
}
Delete a Rule to Rewrite Headers from Request
Delete a Rule to Rewrite Headers from Request
Request example:
curl -k -X DELETE -H "ZAPI_KEY: <ZAPI_KEY_STRING>"
https://<relianoid_server>:444/api/v4.0/api.cgi/farms/MyHttpFarm/services/MyService/replacerequestheader/Index
zcli farm-service-replacerequestheader remove MyHttpFarm MyService Index
This call is available from version 4.0.2
DELETE /farms/<farmname>/service/<servicename>/replacerequestheader/<index>
index is the index of the replacerequestheader array to delete.
Response example:
{
"description" : "Add a Replace Header.",
"message" : "Added a new replace header",
"success" : "true"
}
Add a Rule to Rewrite Headers from Response
Add a Rule to Rewrite Headers from Response
Request example:
curl -k -X POST -H 'Content-Type: application/json' -H "ZAPI_KEY: <ZAPI_KEY_STRING>"
-d '{"header":"^Cookie:", "match":"^COOKIESESSION=(.*)", "replace":"COOKIEUSER=$1`"}'
https://<relianoid_server>:444/api/v4.0/api.cgi/farms/MyHttpFarm/services/MyService/replaceresponseheader
zcli farm-service-replaceresponseheader add farm1 -header "^Cookie:" -match "^COOKIESESSION=(.*)" -replace "COOKIEUSER=$1`"
This call is available from version 4.0.2
POST /farms/<farmname>/service/<servicename>/replaceresponseheader
Add rules to rewrite headers from the response.
Request parameters
Field | Type | Description | Required |
---|---|---|---|
header | String | Regex with the header name to be rewrited | true |
match | String | Regex value to match what we want to replace | true |
replace | String | Value to replace matches | true |
Response example:
{
"description" : "Add a Replace Header.",
"message" : "Added a new replace header",
"success" : "true"
}
Move a Rewrite Headers from Request rule
Move a Rewrite Headers from Request rule
Request example:
curl -k -X POST -H 'Content-Type: application/json' -H "ZAPI_KEY: <ZAPI_KEY_STRING>"
-d '{"position":1}'
https://<relianoid_server>:444/api/v4.0/api/v4.0/zapi.cgi/farms/MyHttpFarm/services/MyService/replacerequestheader/id/actions
farm-replace-response-header add farm1 -header ^Cookie: -match ^COOKIESESSION=(.*) -replace COOKIEUSER=$1`
This call is available from version 4.0.2
POST /farms/<farmname>/services/<service>/replacerequestheader/<id>/actions
Move a ReplaceRequest Header.
Request parameters
Field | Type | Description | Required |
---|---|---|---|
position | Number | New rule position | true |
Response example:
{
"description" : "Move a replace header directive",
"message" : "Header was moved successfully.",
"params" : {
"position" : "1"
}
}
Modify a Rewrite Headers from Response rule
Modify a Rewrite Headers from Response rule
Request example:
curl -k -X PUT -H 'Content-Type: application/json' -H "ZAPI_KEY: <ZAPI_KEY_STRING>"
-d '{"header":"^Cookie:", "match":"^COOKIESESSION=(.*)", "replace":"COOKIEUSER=$1`"}'
https://<relianoid_server>:444/api/v4.0/api.cgi/farms/MyHttpFarm/services/MyService/replaceresponseheader/id
zcli farm-service-replaceresponseheader add farm1 -header "^Cookie:" -match "^COOKIESESSION=(.*)" -replace "COOKIEUSER=$1`"
This call is available from version 4.0.2
PUT /farms/<farmname>/service/<servicename>/replaceresponseheader/<id>
Add rules to rewrite headers from the response.
Request parameters
Field | Type | Description | Required |
---|---|---|---|
header | String | Regex with the header name to be rewrited | true |
match | String | Regex value to match what we want to replace | true |
replace | String | Value to replace matches | true |
Response example:
{
"description" : "Modify a replaceHeader directive.",
"message" : "Modified an item from the replaceHeader list",
"success" : "true"
}
Delete a Rule to Rewrite Headers from Response
Delete a Rule to Rewrite Headers from Response
Request example:
curl -k -X DELETE -H "ZAPI_KEY: <ZAPI_KEY_STRING>"
https://<relianoid_server>:444/api/v4.0/api.cgi/farms/MyHttpFarm/services/MyService/replaceresponseheader/Index
zcli farm-service-replaceresponseheader remove MyHttpFarm MyService Index
This call is available from version 4.0.2
DELETE /farms/<farmname>/service/<servicename>/replaceresponseheader/<index>
index is the index of the replaceresponseheader array to delete.
Response example:
{
"description" : "Delete a replace header directive.",
"message" : "The replace header <index> was deleted successfully"
}
Move a Rewrite Headers from Response rule
Move a Rewrite Headers from Response rule
Request example:
curl -k -X POST -H 'Content-Type: application/json' -H "ZAPI_KEY: <ZAPI_KEY_STRING>"
-d '{"position":1}'
https://<relianoid_server>:444/api/v4.0/api/v4.0/zapi.cgi/farms/MyHttpFarm/services/MyService/replaceresponseheader/id/actions
farm-replace-response-header add farm1 -header ^Cookie: -match ^COOKIESESSION=(.*) -replace COOKIEUSER=$1`
This call is available from version 4.0.2
POST /farms/<farmname>/services/<service>/replaceresponseheader/<id>/actions
Move a ReplaceRequest Header.
Request parameters
Field | Type | Description | Required |
---|---|---|---|
position | Number | New rule position | true |
Response example:
{
"description" : "Move a replace header directive",
"message" : "Header was moved successfully.",
"params" : {
"position" : "1"
}
}
Add a Rule to Add a Header to the Request
Add a Rule to Add a Header to Request
Request example:
curl -k -X POST -H 'Content-Type: application/json' -H "ZAPI_KEY: <ZAPI_KEY_STRING>"
-d '{"header":"header: value"}'
https://<relianoid_server>:444/api/v4.0/api.cgi/farms/MyHttpFarm/services/MyService/addrequestheader
farm-service-addrequestheader add farm1 -header "header: value"
This call is available from version 4.0.2
POST /farms/<farmname>/services/<service>/addrequestheader
Add rules to rewrite headers from the request.
Request parameters
Field | Type | Description | Required |
---|---|---|---|
header | String | Regex with the header name to be rewrited | true |
Response example:
{
"description" : "Add a AddHeader.",
"message" : "Added a new add request header",
"success" : "true"
}
Modify an Add a Header to the Request rule
Modify an Add a Header to the Request rule
Request example:
curl -k -X PUT -H 'Content-Type: application/json' -H "ZAPI_KEY: <ZAPI_KEY_STRING>"
-d '{"header":"header: value"}'
https://<relianoid_server>:444/api/v4.0/api.cgi/farms/MyHttpFarm/services/MyService/addrequestheader/id
farm-service-addrequestheader add farm1 -header "header: value"
This call is available from version 4.0.2
PUT /farms/<farmname>/services/<service>/addrequestheader/<id>
Add rules to rewrite headers from the request.
Request parameters
Field | Type | Description | Required |
---|---|---|---|
header | String | Regex with the header name to be rewrited | true |
Response example:
{
"description" : "Add a AddHeader.",
"message" : "Added a new add request header",
"success" : "true"
}
Delete a Rule to Add a Header to the Request
Delete a Rule to Add a Header to the Request
Request example:
curl -k -X DELETE -H "ZAPI_KEY: <ZAPI_KEY_STRING>"
https://<relianoid_server>:444/api/v4.0/api.cgi/farms/MyHttpFarm/services/MyService/addrequestheader/Index
zcli farm-service-addrequestheader remove MyHttpFarm MyService Index
This call is available from version 4.0.2
DELETE /farms/<farmname>/services/<service>/addrequestheader/<index>
index is the index of the replacerequestheader array to delete.
Response example:
{
"message": "The add request header <index> has been deleted successfully"
}
Add a Rule to Add a Header to the Response
Add a Rule to Add a Header to Response
Request example:
curl -k -X POST -H 'Content-Type: application/json' -H "ZAPI_KEY: <ZAPI_KEY_STRING>"
-d '{"header":"header: value"}'
https://<relianoid_server>:444/api/v4.0/api.cgi/farms/MyHttpFarm/services/MyService/addresponseheader
zcli farm-service-addresponseheader add farm1 -header "header: value"
This call is available from version 4.0.2
POST /farms/<farmname>/services/<service>/addresponseheader
Add rules to rewrite headers from the response.
Request parameters
Field | Type | Description | Required |
---|---|---|---|
header | String | Regex with the header name to be rewrited | true |
Response example:
{
"description" : "Add a AddHeader.",
"message" : "Added a new add request header",
"success" : "true"
}
Modify an Add a Header to the Response rule
Modify an Add a Header to the Response rule
Request example:
curl -k -X POST -H 'Content-Type: application/json' -H "ZAPI_KEY: <ZAPI_KEY_STRING>"
-d '{"header":"header: value"}'
https://<relianoid_server>:444/api/v4.0/api.cgi/farms/MyHttpFarm/services/MyService/addresponseheader/id
zcli farm-service-addresponseheader add farm1 -header "header: value"
This call is available from version 4.0.2
PUT /farms/<farmname>/services/<service>/addresponseheader/<id>
Add rules to rewrite headers from the response.
Request parameters
Field | Type | Description | Required |
---|---|---|---|
header | String | Regex with the header name to be rewrited | true |
Response example:
{
"description" : "Modify an addheader directive.",
"message" : "Modified an item from the addheader list",
"success" : "true"
}
Delete a Rule to Add a Header to the Response
Delete a Rule to Add a Header to the Response
Request example:
curl -k -X DELETE -H "ZAPI_KEY: <ZAPI_KEY_STRING>"
https://<relianoid_server>:444/api/v4.0/api.cgi/farms/MyHttpFarm/services/MyService/addresponseheader/Index
zcli farm-service-addresponseheader remove MyHttpFarm MyService Index
This call is available from version 4.0.2
DELETE /farms/<farmname>/services/<service>/addrequestheader/<index>
index is the index of the replaceresponseheader array to delete.
Response example:
{
"message": "The add response header 0 has been deleted successfully"
}
Add Rule to Remove Headers from the Request
Add Rule to Remove Headers from the Request
Request example:
curl -k -X POST -H 'Content-Type: application/json' -H "ZAPI_KEY: <ZAPI_KEY_STRING>"
-d '{"pattern":"^client:"}' https://<relianoid_server>:444/api/v4.0/api.cgi/farms/MyHttpFarm/services/MyService/removerequestheader
zcli farm-service-removerequestheader add MyHttpFarm -pattern "^client:""
POST /farms/<farmname>/service/<servicename>/removerequestheader
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:
{
"message": "Added a new remove request header"
}
Modify Rule to Remove Headers from the Request
Modify Rule to Remove Headers from the Request
Request example:
curl -k -X PUT -H 'Content-Type: application/json' -H "ZAPI_KEY: <ZAPI_KEY_STRING>"
-d '{"pattern":"^client:"}' https://<relianoid_server>:444/api/v4.0/api.cgi/farms/MyHttpFarm/services/MyService/removerequestheader/id
zcli farm-service-removerequestheader add MyHttpFarm -pattern "^client:""
PUT /farms/<farmname>/service/<servicename>/removerequestheader/<id>
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" : "Modify RemoveResponseHeader directive.",
"message" : "Modify an item from the removeresponseheader list",
"success" : "true"
}
Delete a Rule to Remove Headers from the Request
Delete a Rule to Remove Headers from the Request
Request example:
curl -k -X DELETE -H "ZAPI_KEY: <ZAPI_KEY_STRING>"
https://<relianoid_server>:444/api/v4.0/api.cgi/farms/MyHttpFarm/services/MyService/removerequestheader/Index
zcli farm-remove-request-header remove MyHttpFarm Service Index
DELETE /farms/<farmname>/service/<service0>/removerequestheader/<index>
index is the index of the removerequestheader array to delete.
Response example:
{
"message": "The remove request header <index> has been deleted successfully"
}
Add Rule to Remove Headers from the Response
Add Rule to Remove Headers from the Response
Request example:
curl -k -X POST -H 'Content-Type: application/json' -H "ZAPI_KEY: <ZAPI_KEY_STRING>"
-d '{"pattern":"^client:"}' https://<relianoid_server>:444/api/v4.0/api.cgi/farms/MyHttpFarm/services/MyService/removeresponseheader
zcli farm-service-removeresponseheader add MyHttpFarm -pattern "^client:""
POST /farms/<farmname>/service/<servicename>/removeresponseheader
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:
{
"message": "Added a new remove response header"
}
Modify a Remove Headers from the Response rule
Modify a Remove Headers from the Response rule
Request example:
curl -k -X POST -H 'Content-Type: application/json' -H "ZAPI_KEY: <ZAPI_KEY_STRING>"
-d '{"pattern":"^client:"}' https://<relianoid_server>:444/api/v4.0/api.cgi/farms/MyHttpFarm/services/MyService/removeresponseheader/id
zcli farm-service-removeresponseheader add MyHttpFarm -pattern "^client:""
PUT /farms/<farmname>/service/<servicename>/removeresponseheader/<id>
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" : "Modify RemoveResponseHeader directive.",
"message" : "Modify an item from the removeresponseheader list",
"success" : "true"
}
Delete a Rule to Remove Headers from the Response
Delete a Rule to Remove Headers from the Response
Request example:
curl -k -X DELETE -H "ZAPI_KEY: <ZAPI_KEY_STRING>"
https://<relianoid_server>:444/api/v4.0/api.cgi/farms/MyHttpFarm/services/MyService/removeresponseheader/Index
zcli farm-remove-request-header remove MyHttpFarm Service Index
DELETE /farms/<farmname>/service/<service0>/removeresponseheader/<index>
index is the index of the removeresponseheader array to delete.
Response example:
{
"message": "The remove request header <index> has been deleted successfully"
}
Add Rule to checks and rewrite patterns from URL
Add Rule to checks and rewrite patterns from URL
Request example:
curl -k -X POST -H 'Content-Type: application/json' -H "ZAPI_KEY: <ZAPI_KEY_STRING>"
-d '{"pattern":"/media/(.+)$","replace":"/svc1/$1","last":"true"}' https://<relianoid_server>:444/api/v4.0/api.cgi/farms/MyHttpFarm/services/MyService/rewriteurl
zcli farm-service-rewriteurl add MyHttpFarm MyService -pattern "/media/(.+)$" -replace "/svc1/$1" -last "true"
POST /farms/<farmname>/service/<servicename>/rewriteurl
From version 4.0.2. It checks a pattern in order to get strings from URL and replace them.
Request parameters
Field | Type | Description | Required |
---|---|---|---|
pattern | String | It is a string with a regexp to look for in the url. If url matches in the pattern, the matched text will be replaced | true |
replace | String | It is a string to replace the matched text | true |
last | String | True or False. If true is set, that will finish the rewrite url phase | true |
Response example:
{
"message": "Added a new rewriteurl"
}
Modify Rule of checks and rewrite patterns from URL
Modify Rule of checks and rewrite patterns from URL
Request example:
curl -k -X PUT -H 'Content-Type: application/json' -H "ZAPI_KEY: <ZAPI_KEY_STRING>"
-d '{"pattern":"/media/(.+)$","replace":"/svc1/$1","last":"true"}' https://<relianoid_server>:444/api/v4.0/api.cgi/farms/MyHttpFarm/services/MyService/rewriteurl/id
zcli farm-service-rewriteurl add MyHttpFarm MyService -pattern "/media/(.+)$" -replace "/svc1/$1" -last "true"
PUT /farms/<farmname>/service/<servicename>/rewriteurl/<id>
From version 4.0.2. It checks a pattern in order to get strings from URL and replace them.
Request parameters
Field | Type | Description | Required |
---|---|---|---|
pattern | String | It is a string with a regexp to look for in the url. If url matches in the pattern, the matched text will be replaced | true |
replace | String | It is a string to replace the matched text | true |
last | String | True or False. If true is set, that will finish the rewrite url phase | true |
Response example:
{
"description" : "Modify a RewriteUrl.",
"message" : "Modify a new rewrite url",
"success" : "true"
}
Delete a Rule to checks and rewrite patterns from URL
Delete a Rule to checks and rewrite patterns from URL
Request example:
curl -k -X DELETE -H "ZAPI_KEY: <ZAPI_KEY_STRING>"
https://<relianoid_server>:444/api/v4.0/api.cgi/farms/MyHttpFarm/services/MyService/rewriteurl/Index
zcli arm-service-rewriteurl remove MyHttpFarm Service Index
DELETE /farms/<farmname>/service/<service0>/rewriteurl/<index>
From version 4.0.2. index is the index of the rewriteurl array to delete.
Response example:
{
"message": "The rewriteurl <index> has been deleted successfully"
}
Move a checks and rewrite patterns from URL rule
Move a checks and rewrite patterns from URL rule
Request example:
curl -k -X POST -H 'Content-Type: application/json' -H "ZAPI_KEY: <ZAPI_KEY_STRING>"
-d '{"position":1}'
https://<relianoid_server>:444/api/v4.0/api/v4.0/zapi.cgi/farms/MyHttpFarm/services/MyService/rewriteurl/id/actions
farm-replace-response-header add farm1 -header ^Cookie: -match ^COOKIESESSION=(.*) -replace COOKIEUSER=$1`
This call is available from version 4.0.2
POST /farms/<farmname>/services/<service>/rewriteurl/<id>/actions
Move a ReplaceRequest Header.
Request parameters
Field | Type | Description | Required |
---|---|---|---|
position | Number | New rule position | true |
Response example:
{
"description" : "Move a rewriteurl directive",
"message" : "Header was moved successfully.",
"params" : {
"position" : "1"
}
}
List the sessions
List the sessions
Request example:
curl -k -X GET -H 'Content-Type: application/json' -H "ZAPI_KEY: <ZAPI_KEY_STRING>"
https://<relianoid_server>:444/api/v4.0/api.cgi/farms/farm1/services/service0/sessions
zcli farm-service-session list farm1 service0
GET /farms/<farmname>/services/<servicename>/sessions
From version 4.0.2. Get the list of sessions in the farm:service. Property only avaliable for proxy of new generation zproxy.
Response example:
{
"description" : "Get farm sessions",
"params": [
{
"id": "0",
"session": "10.0.0.2",
"ttl": null,
"type": "static"
},
{
"id": "0",
"session": "10.0.0.2",
"ttl": "58m28s148ms",
"type": "dynamic"
},
{
"id": "0",
"session": "10.0.0.2",
"ttl": "59m56s496ms",
"type": "dynamic"
}
]
}
Response Parameters
This request returns a list of sessions object, each session object contains the following keys:
Field | Type | Description |
---|---|---|
id | Number | Backend ID which will receive the connection. |
session | String | It is the session identifier or a connection, its value depend on the persistence parameter of the farm. If persistence is 'IP' session should be a IPv4 or IPv6, e.g. 192.168.42.65; |
type | String | There are two type of sessions: dynamic is a connection that load balancer pins with a backend using the farm load balancing algorithm; static is a connection that the load balancer administrator pins with a backend. The static sessions will not be redirect to another backend if its backed in unreachable. |
ttl | String | It is a string with the session time to expire. The ttl value will be null if the session is not of type static. |
Add a session
Add a session
Request example:
curl -k -X POST -H 'Content-Type: application/json' -H "ZAPI_KEY: <ZAPI_KEY_STRING>"
-d '{"session":"10.0.0.2","id":0}' https://<relianoid_server>:444/api/v4.0/api.cgi/farms/farm1/services/service0/sessions
zcli farm-service-session add farm1 service0 -backend 0 -session 10.0.0.2
POST /farms/<farmname>/services/<servicename>/sessions
From version 4.0.2. It creates a static session with a backend in a session. The input connection that matches with the session will be forwarded always to that backend. Property only avaliable for proxy of new generation zproxy.
Request parameters
Field | Type | Description |
---|---|---|
id | Number | Backend ID which will receive the connection. |
session | String | It is the session identifier or a connection, its value depend on the persistence parameter of the farm. If persistence is 'IP', session should be a IPv4 or IPv6, e.g. 192.168.42.65; |
Response example:
{
"description" : "Adding a static session to the farm1",
"message" : "Added a session for the farm 'farm1'",
"params" : {
"id" : "0",
"session" : "10.0.0.1",
"ttl" : null,
"type" : "static"
}
}
Response Parameters
This request returns session object that contains the following keys:
Field | Type | Description |
---|---|---|
id | Number | Backend ID which will receive the connection. |
session | String | It is the session identifier or a connection, its value depend on the persistence parameter of the farm. If persistence is 'IP', session should be a IPv4 or IPv6, e.g. 192.168.42.65. |
ttl | String | It is a string with the session time to expire. The ttl value will be null if the session is of type static. |
type | String | There are two type of sessions: dynamic is a connection that load balancer pins with a backend using the farm load balancing algorithm; static is a connection that the load balancer administrator pins with a backend. The static sessions will not be redirect to another backend if its backed in unreachable. |
Remove a session
Remove a session
Request example:
curl -k -X DELETE -H "ZAPI_KEY: <ZAPI_KEY_STRING>"
https://<relianoid_server>:444/api/v4.0/api.cgi/farms/farm1/services/service0/sessions/10.0.0.1
zcli farm-service-session remove farm1 service0 10.0.0.1
DELETE /farms/<farmname>/services/<servicename>/sessions/<session>
It deletes a static session.
Response example:
{
"description" : "Delete a 'static' session",
"message" : "The session '10.0.0.1' was deleted properly from the farm 'farm1'.",
"success" : "true"
}
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://<relianoid_server>:444/api/v4.0/api.cgi/farms/httpfarm/services/service1/backends
zcli farm get httpfarm
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,
"priority" : null,
"connection_limit" : null
},
{
"alias" : null,
"id" : 1,
"ip" : "192.168.102.245",
"port" : 80,
"status" : "up",
"timeout" : 22,
"weight" : 2,
"priority" : null,
"connection_limit": null
}
]
}
Response Parameters
This call returns a backend object array with the bellow parameters.
Field | Type | Description |
---|---|---|
id | Number | unique identifier for the backend in the service. This identifier is generated by the system. |
ip | String | Backend's IP where the real service is listening. |
port | Number | Backend's port where the real service is listening. |
timeout | Number | It’s the backend timeout to respond a certain request, in seconds. |
weight | Number | It's the weight value for the current backend. 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. |
priority (from 4.0.1) | Number | The priority value for the current real server (accepted values are 1 or 2). Lower values have more priority and the default value is 1, so the backend will be used anytime it is available. If all backends with priority 1 are down or in maintenance, the backend with priority 2 is enabled to maintain the service available. Only one backend with priority 2 is allowed currently. |
Field | Type | Description |
---|---|---|
alias | String | It is a nick to help to identify the backend. Alias |
connection_limit (from 4.0.2) | Number | The maximum number of established connection per backend. With a value of 0, there will not be a limit in the backend. The client will receive a 503 error if there aren't available backends. |
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,"priority":1,"connection_limit":10}'
https://<relianoid_server>:444/api/v4.0/api.cgi/farms/httpfarm/services/newsrv/backends
zcli farm-service-backend add httpfarm newsrv -ip 192.168.102.244 -port 80 -timeout 2 -priority 1 -weight 2 -connection_limit 10
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. | |
priority (from 4.0.1) | Number | IThe priority value for the current real server (accepted values are 1 or 2). Lower values have more priority and the default value is 1, so the backend will be used anytime it is available. If all backends with priority 1 are down or in maintenance, the backend with priority 2 is enabled to maintain the service available. Only one backend with priority 2 is allowed currently. |
Field | Type | Description |
---|---|---|
connection_limit (from 4.0.2) | Number | The maximum number of established connection per backend. With a value of 0, there will not be a limit in the backend. The client will receive a 503 error if there aren't available backends. |
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,
"priority" : 1,
"connection_limit" : 10
},
"status" : "needed restart"
}
Response Parameters
The response will be a JSON with requested parameters updated and the status field with the current status of the farm. If Restart action needs to be taken to apply the changes of the farm, the value will be needed restart.If there is
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,"weight":1,"priority":1,"connection_limit":10}'
https://<relianoid_server>:444/api/v4.0/api.cgi/farms/FarmHTTP/service/service1/backends/1
zcli farm-service-backend set FarmHTTP service1 1 -ip 192.168.0.10 -port 88 -timeout 12 -weight 1 -priority 1 -connection_limit 10
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. |
priority (from 4.0.1) | Number | The priority value for the current real server (accepted values are 1 or 2). Lower values have more priority and the default value is 1, so the backend will be used anytime it is available. If all backends with priority 1 are down or in maintenance, the backend with priority 2 is enabled to maintain the service available. Only one backend with priority 2 is allowed currently. |
Field | Type | Description |
---|---|---|
connection_limit (from 4.0.2) | Number | The maximum number of established connection per backend. With a value of 0, there will not be a limit in the backend. The client will receive a 503 error if there aren't available backends. |
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,
"priority" : 4,
"connection_limit" : 10
},
"status" : "needed restart",
"warning" : "Backends with high priority value (4) will not be used."
}
Response Parameters
The response will be a JSON with requested parameters updated and the status field with the current status of the farm. If Restart action needs to be taken to apply the changes of the farm, the value will be needed restart. If Priority parameter is updated whith a inconsistent value, the warning field will describe it.
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://<relianoid_server>:444/api/v4.0/api.cgi/farms/httpfarm/services/newsrv/backends/0/maintenance
zcli farm-service-backend maintenance httpfarm newsrv 0 -mode cut
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://<relianoid_server>:444/api/v4.0/api.cgi/farms/newfarmHTTP/services/service1/backends/4
zcli farm-service-backend remove newfarmHTTP service1 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://<relianoid_server>:444/api/v4.0/api.cgi/farms/l4farm
zcli farm get 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",
"sessions": []
}
}
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. |
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. |
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 in maintenance mode; problem, the farm is up and there are some backends that are unreachable, but at least one backend has the "up" status; maintenance, the farm is up and there are backends in up status, but at least 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. 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. |
+ in EE version:
Field | Type | Description |
---|---|---|
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. |
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. |
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. |
sessions (from version 4.0.2) | Object[] | List of static and dynamic sessions created for this farm. |
Backend object for L4xNAT farms:
Field | Type | Description |
---|---|---|
id | Number | ID to identify the backend in the farm backends pool. |
ip | String | Backend's IP 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. |
priority | Number | It’s the priority value for the current real server. Backend with lower priority value will be ready to receive connections before than others with higher priority. Default value null, a priority value 1 is used. The possible values are are from 1 to 9. |
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. |
+ in EE version:
Field | Type | Description |
---|---|---|
alias | String | It is a nick to help to identify the backend. Alias |
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 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. |
Session object for L4xNAT farms:
Field | Type | Description |
---|---|---|
client | Number | It is a client identifier. |
id | Number | Backend ID which will receive the connection. |
session | String | It is the session identifier or a connection, its value depend on the persistence parameter of the farm. If persistence is 'mac', session should be a MAC, e.g. 02:8e:69:38:12:8e; if persistence is 'ip' or 'srcip', session should be a IPv4 or IPv6, e.g. 192.168.42.65; if persistence is 'port', session should be a valid port, e.g. 5445; if persistence is 'srcip_srcport' or 'srcip_dstport' ; session should be a string with an IP and a port joined by underscope '_', e.g. 122.36.54.2_80. |
ttl | String | It is a string with the session time to expire. The ttl value will be null if the session is of type static. |
type | String | There are two type of sessions: dynamic is a connection that load balancer pins with a backend using the farm load balancing algorithm; static is a connection that the load balancer administrator pins with a backend. The static sessions will not be redirect to another backend if its backed in unreachable. |
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://<relianoid_server>:444/api/v4.0/api.cgi/farms
zcli farm create -farmname newl4farm -vip 192.168.100.241 -vport 88 -profile l4xnat
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 |
+ in EE version:
Field | Type | Description |
---|---|---|
copy_from (from 4.0.1) | String | This parameter expects the name of a farm that exists. If this parameter is sent, the farm is copied from the farm specified in it. The farmname, vip and vport values will be overwritten. |
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://<relianoid_server>:444/api/v4.0/api.cgi/farms/newfarml4
zcli farm set newfarml4 -algorithm weight -newfarmname l4farm -protocol tcp -nattype nat -ttl 125 -vip 178.62.126.152 -vport 81 -logs true
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. |
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 ,. |
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. |
+ in EE version:
Field | Type | Description |
---|---|---|
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. |
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. |
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://<relianoid_server>:444/api/v4.0/api.cgi/farms/l4Farm/fg
zcli farm-service-farmguardian add l4Farm default_service -name check_tcp-cut_conns
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://<relianoid_server>:444/api/v4.0/api.cgi/farms/l4Farm/fg/check_tcp-cut_conns
zcli farm-service-farmguardian remove l4Farm default_service 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 POST /farms/<farmname>/sessions
Add DELETE /farms/<farmname>/sessions/<session>
List the sessions
List the sessions
Request example:
curl -k -X GET -H 'Content-Type: application/json' -H "ZAPI_KEY: <ZAPI_KEY_STRING>"
https://<relianoid_server>:444/api/v4.0/api.cgi/farms/farm1/sessions
zcli farm-session list farm1
GET /farms/<farmname>/sessions
Get the list of sessions in the farm.
Response example:
{
"description" : "Get farm sessions",
"params": [
{
"client": 0,
"id": "0",
"session": "10.0.0.2_56",
"ttl": null,
"type": "static"
},
{
"client": 1,
"id": "0",
"session": "10.0.0.2_54936",
"ttl": "58m28s148ms",
"type": "dynamic"
},
{
"client": 2,
"id": "0",
"session": "10.0.0.2_54968",
"ttl": "59m56s496ms",
"type": "dynamic"
}
]
}
Response Parameters
This request returns a list of sessions objects, each session object contains the following keys:
Field | Type | Description |
---|---|---|
client | Number | It is a client identifier. |
id | Number | Backend ID which will receive the connection. |
session | String | It is the session identifier or a connection, its value depend on the persistence parameter of the farm. If persistence is 'mac', session should be a MAC, e.g. 02:8e:69:38:12:8e; if persistence is 'ip' or 'srcip', session should be a IPv4 or IPv6, e.g. 192.168.42.65; if persistence is 'port', session should be a valid port, e.g. 5445; if persistence is 'srcip_srcport' or 'srcip_dstport' ; session should be a string with an IP and a port joined by underscope '_', e.g. 122.36.54.2_80. |
ttl | String | It is a string with the session time to expire. The ttl value will be null if the session is of type static. |
type | String | There are two type of sessions: dynamic is a connection that load balancer pins with a backend using the farm load balancing algorithm; static is a connection that the load balancer administrator pins with a backend. The static sessions will not be redirect to another backend if its backed in unreachable. |
Add a session
Add a session
Request example:
curl -k -X POST -H 'Content-Type: application/json' -H "ZAPI_KEY: <ZAPI_KEY_STRING>"
-d '{"session":"10.0.0.2_56","id":0}' https://<relianoid_server>:444/api/v4.0/api.cgi/farms/farm1/sessions
zcli farm-session add farm1 -id 0 -session 10.0.0.2_56
POST /farms/<farmname>/sessions
It creates a static session with a backend. The input connection that matches with the session will be forwarded always to that backend.
Request parameters
Field | Type | Description |
---|---|---|
id | Number | Backend ID which will receive the connection. |
session | String | It is the session identifier or a connection, its value depend on the persistence parameter of the farm. If persistence is 'mac', session should be a MAC, e.g. 02:8e:69:38:12:8e; if persistence is 'ip' or 'srcip', session should be a IPv4 or IPv6, e.g. 192.168.42.65; if persistence is 'port', session should be a valid port, e.g. 5445; if persistence is 'srcip_srcport' or 'srcip_dstport' ; session should be a string with an IP and a port joined by underscope '_', e.g. 122.36.54.2_80. |
Response example:
{
"description" : "Adding a static session to the farm1",
"message" : "Added a session for the farm 'farm1'",
"params" : {
"client" : 1,
"id" : "0",
"session" : "10.0.0.1_56",
"ttl" : null,
"type" : "static"
}
}
Response Parameters
This request returns session object that contains the following keys:
Field | Type | Description |
---|---|---|
client | Number | It is a client identifier. |
id | Number | Backend ID which will receive the connection. |
session | String | It is the session identifier or a connection, its value depend on the persistence parameter of the farm. If persistence is 'mac', session should be a MAC, e.g. 02:8e:69:38:12:8e; if persistence is 'ip' or 'srcip', session should be a IPv4 or IPv6, e.g. 192.168.42.65; if persistence is 'port', session should be a valid port, e.g. 5445; if persistence is 'srcip_srcport' or 'srcip_dstport' ; session should be a string with an IP and a port joined by underscope '_', e.g. 122.36.54.2_80. |
ttl | String | It is a string with the session time to expire. The ttl value will be null if the session is of type static. |
type | String | There are two type of sessions: dynamic is a connection that load balancer pins with a backend using the farm load balancing algorithm; static is a connection that the load balancer administrator pins with a backend. The static sessions will not be redirect to another backend if its backed in unreachable. |
Remove a session
Remove a session
Request example:
curl -k -X DELETE -H "ZAPI_KEY: <ZAPI_KEY_STRING>"
https://<relianoid_server>:444/api/v4.0/api.cgi/farms/farm1/sessions/10.0.0.1_56
zcli farm-session remove farm1 10.0.0.1_56
DELETE /farms/<farmname>/sessions/<session>
It deletes a static session.
Response example:
{
"description" : "Delete a 'static' session",
"message" : "The session '10.0.0.1_56' was deleted properly from the farm 'farm1'.",
"success" : "true"
}
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://<relianoid_server>:444/api/v4.0/api.cgi/farms/l4Farm/ipds/blacklists
zcli farm-blacklist add l4Farm -name china
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://<relianoid_server>:444/api/v4.0/api.cgi/farms/l4Farm/ipds/blacklists/china
zcli farm-blacklist remove l4Farm 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://<relianoid_server>:444/api/v4.0/api.cgi/farms/l4farm/backends
zcli farm get l4farm
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 |
---|---|---|
id | Number | ID to identify the backend in the farm backends pool. |
ip | String | Backend's IP 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. |
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. |
+ in EE version:
Field | Type | Description |
---|---|---|
alias | String | It is a nick to help to identify the backend. Alias |
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. |
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://<relianoid_server>:444/api/v4.0/api.cgi/farms/l4farm/backends
zcli farm-service-backend add l4farm default_service -ip 192.168.5.100 -port 8080 -max_conns 400
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 |
priority | Number | It’s the priority value for the current real server. Backend with lower priority value will be ready to receive connections before than others with higher priority. Default value null, a priority value 1 is used. The possible values are are from 1 to 9. | |
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. |
+ in EE version:
Field | Type | Description |
---|---|---|
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. |
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://<relianoid_server>:444/api/v4.0/api.cgi/farms/l4farm/backends/2
zcli farm-service-backend set l4farm default_service 2 -ip 192.168.5.40 -port 8080 -max_conns 220 -priority 4 -weight 7
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. |
priority | Number | It’s the priority value for the current real server. Backend with lower priority value will be ready to receive connections before than others with higher priority. Default value null, a priority value 1 is used. The possible values are are from 1 to 9. |
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. |
+ in EE version:
Field | Type | Description |
---|---|---|
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. |
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://<relianoid_server>:444/api/v4.0/api.cgi/farms/l4farm/backends/1/maintenance
zcli farm-service-backend maintenance l4farm default_service 1 -mode cut
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://<relianoid_server>:444/api/v4.0/api.cgi/farms/l4farm/backends/4
zcli farm-service-backend remove l4farm default_service 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://<relianoid_server>:444/api/v4.0/api.cgi/farms/gslbfarm
zcli farm get 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://<relianoid_server>:444/api/v4.0/api.cgi/farms
zcli farm create -farmname gslbfarm -vip 192.168.100.241 -vport 53 -profile gslb
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 |
copy_from (from 4.0.1) | String | This parameter expects the name of a farm that exists. If this parameter is sent, the farm is copied from the farm specified in it. The farmname, vip and vport values will be overwritten. |
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://<relianoid_server>:444/api/v4.0/api.cgi/farms/gslbfarm
zcli farm set gslbfarm -newfarmname gslbnewname -vip 192.168.100.155 -vport 60
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://<relianoid_server>:444/api/v4.0/api.cgi/farms/gslbFarm/ipds/blacklists
zcli farm farm-blacklist add gslbFarm -name china
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://<relianoid_server>:444/api/v4.0/api.cgi/farms/gslbFarm/ipds/blacklists/china
zcli farm-blacklist remove gslbFarm 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://<relianoid_server>:444/api/v4.0/api.cgi/farms/gslbfarm/services
zcli farm-service add gslbfarm -id service1 -algorithm roundrobin
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://<relianoid_server>:444/api/v4.0/api.cgi/farms/gslbfarm/services/service1
zcli farm-service set gslbfarm service1 -deftcpport 53
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://<relianoid_server>:444/api/v4.0/api.cgi/farms/gslbfarm/service/service1/fg
zcli farm-service-farmguardian add gslbfarm service1 -name dns-request
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://<relianoid_server>:444/api/v4.0/api.cgi/farms/gslbfarm/service/service1/fg/dns-request
zcli farm-service-farmguardian remove gslbfarm service1 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://<relianoid_server>:444/api/v4.0/api.cgi/farms/gslbfarm/services/service1
zcli farm-service remove gslbfarm 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://<relianoid_server>:444/api/v4.0/api.cgi/farms/gslbfarm/services/service1/backends
zcli farm get gslbfarm
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://<relianoid_server>:444/api/v4.0/api.cgi/farms/gslbfarm/services/service1/backends
zcli farm-service-backend add gslbfarm service1 -ip 192.135.10.2
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://<relianoid_server>:444/api/v4.0/api.cgi/farms/gslbfarm/services/service1/backends/1
zcli farm-service-backend set gslbfarm service1 1 -ip 192.168.2.30
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://<relianoid_server>:444/api/v4.0/api.cgi/farms/gslbfarm/services/service1/backends/3
zcli farm-service-backend remove gslbfarm service1 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.com"}'
https://<relianoid_server>:444/api/v4.0/api.cgi/farms/gslbfarm/zones
zcli farm-zone add gslbfarm -id global.com
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://<relianoid_server>:444/api/v4.0/api.cgi/farms/gslbfarm/zones/global.com
zcli farm-zone set gslbfarm global.com -defnamesv ns3
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://<relianoid_server>:444/api/v4.0/api.cgi/farms/gslbfarm/zones/dom.com
zcli farm-zone remove gslbfarm 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 RELIANOID load balances are:
- NS. Name Server type record, it delegates a DNS zone to use the given authoritative name servers.
- A. Address type record, it returns an IPv4 address of a host.
- CNAME. Canonical name type record, it represents an alias of a given name.
- DYNA. Dynamic address type record, it returns a dynamic address specified by a GSLB service already created within the farm configuration according to the algorithm selected for such service.
- AAAA. Address type record, it returns an IPv6 address of a host.
- MX. Mail exchange type record, maps a domain name to a list of message transfer agents for that domain.
- SRV. Service locator type record, Generalized service location record, used for newer protocols instead of creating protocol-specific records such as MX.
- TXT. Text type record, it is used to store any text-based information that can be grabbed when necessary. We most commonly see TXT records used to hold SPF data and verify domain ownership.
- PTR. Pointer record, 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.
- 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://<relianoid_server>:444/api/v4.0/api.cgi/farms/gslbfarm/zones/global.com/resources
zcli farm-zone-resource list gslbfarm global.com
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://<relianoid_server>:444/api/v4.0/api.cgi/farms/gslbfarm/zones/global.com/resources
zcli farm-zone-resource add gslbfarm global.com -rname resource2 -rdata 192.168.0.9 -ttl 10 -type A
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://<relianoid_server>:444/api/v4.0/api.cgi/farms/gslbfarm/zones/global.com/resources/1
zcli farm-zone-resource set gslbfarm global.com 1 -rname resource2 -rdata 192.168.200.30 -type A
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://<relianoid_server>:444/api/v4.0/api.cgi/farms/gslbfarm/zones/global.com/resources/3
zcli farm-zone-resource remove gslbfarm global.com 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 or DSLB (Datalink Service Load Balancing) 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://<relianoid_server>:444/api/v4.0/api.cgi/farms/dlink
zcli farm get 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://<relianoid_server>:444/api/v4.0/api.cgi/farms
zcli farm create -profile datalink -farmname dlink -vip 192.168.100.241
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 |
copy_from (from 4.0.1) | String | This parameter expects the name of a farm that exists. If this parameter is sent, the farm is copied from the farm specified in it. The farmname and vip values will be overwritten. |
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://<relianoid_server>:444/api/v4.0/api.cgi/farms/dlink
zcli farm set dlink -newfarmname dlink2 -vip 192.168.100.199 -algorithm weight
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://<relianoid_server>:444/api/v4.0/api.cgi/farms/dlink2/ipds/blacklists
zcli farm-blacklist add dlink2 -name china
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://<relianoid_server>:444/api/v4.0/api.cgi/farms/dlink2/ipds/blacklists/china
zcli farm-blacklist remove dlink -name 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://<relianoid_server>:444/api/v4.0/api.cgi/farms/dlink/backends
zcli farm get dlink
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://<relianoid_server>:444/api/v4.0/api.cgi/farms/dlink/backends
zcli farm-service-backend add dlink default_service -ip 192.168.100.10 -interface eth0 -priority 2 -weight 2
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://<relianoid_server>:444/api/v4.0/api.cgi/farms/datalink/backends/2
zcli farm-service-backend set datalink default_service 2 -ip 192.168.102.50 -interface eth0 -weight 1 -priority 1
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://<relianoid_server>:444/api/v4.0/api.cgi/farms/dlink/backends/4
zcli farm-service-backend remove dlink default_service 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
RELIANOID 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. RELIANOID 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://<relianoid_server>:444/api/v4.0/api.cgi/interfaces
zcli network list
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 |
---|---|---|
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. |
+ in EE version:
Field | Type | Description |
---|---|---|
alias | String | It is a nick to help to identify the interface. Alias |
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://<relianoid_server>:444/api/v4.0/api.cgi/interfaces/gateway/ipv4
zcli network-default-gateway-ipv4 get
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://<relianoid_server>:444/api/v4.0/api.cgi/interfaces/gateway/ipv4
zcli network-default-gateway-ipv4 set -interface eth0 -address 192.168.100.5
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, RELIANOID 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://<relianoid_server>:444/api/v4.0/api.cgi/interfaces/gateway/ipv4
zcli network-default-gateway-ipv4 delete
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 RELIANOID 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://<relianoid_server>:444/api/v4.0/api.cgi/interfaces/nic
zcli network-nic list
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 |
---|---|---|
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. |
+ in EE version:
Field | Type | Description |
---|---|---|
alias | String | It is a nick to help to identify the interface. Alias |
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://<relianoid_server>:444/api/v4.0/api.cgi/interfaces/nic/eth1
zcli network-nic get 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 |
---|---|---|
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. |
+ in EE version:
Field | Type | Description |
---|---|---|
alias | String | It is a nick to help to identify the interface. Alias |
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://<relianoid_server>:444/api/v4.0/api.cgi/interfaces/nic/eth1
zcli network-nic set eth0 -ip 192.168.100.102 -netmask 255.255.255.0 -gateway 192.168.100.5
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. |
+ in EE version:
Field | Type | Description |
---|---|---|
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" : {
"alias" : null,
"dhcp" : "false",
"gateway" : "192.168.100.5",
"ip" : "192.168.100.102",
"is_slave" : "false",
"mac" : "4a:4f:3c:d7:dd:70",
"name" : "eth1",
"netmask" : "255.255.255.0",
"status" : "down"
}
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://<relianoid_server>:444/api/v4.0/api.cgi/interfaces/nic/eth3
zcli network-nic unset 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://<relianoid_server>:444/api/v4.0/api.cgi/interfaces/nic/eth1/actions
zcli network-nic stop eth1
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://<relianoid_server>:444/api/v4.0/api.cgi/interfaces/vlan
zcli network-vlan list
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 |
---|---|---|
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. |
+ in EE version:
Field | Type | Description |
---|---|---|
alias | String | It is a nick to help to identify the interface. Alias |
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://<relianoid_server>:444/api/v4.0/api.cgi/interfaces/vlan/eth0.1
zcli network-vlan get 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 |
---|---|---|
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. |
+ in EE version:
Field | Type | Description |
---|---|---|
alias | String | It is a nick to help to identify the interface. Alias |
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://<relianoid_server>:444/api/v4.0/api.cgi/interfaces/vlan
zcli network-vlan create -name eth0.1 -ip 192.168.120.120 -netmask 255.255.255.0 -gateway 192.168.120.1 -mac 52:98:19:61:c9:18 -dhcp false
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 |
+ in EE version:
Field | Type | Description |
---|---|---|
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://<relianoid_server>:444/api/v4.0/api.cgi/interfaces/vlan/eth0.1
zcli network-vlan set eth0.1 -ip 192.168.131.151 -netmask 255.255.255.0 -gateway 192.168.131.1 -mac 96:23:25:8b:d4:af
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. |
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. |
+ in EE version:
Field | Type | Description |
---|---|---|
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 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://<relianoid_server>:444/api/v4.0/api.cgi/interfaces/vlan/eth0.1
zcli network-vlan delete 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://<relianoid_server>:444/api/v4.0/api.cgi/interfaces/vlan/eth0.1/actions
zcli network-vlan stop eth0.1
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://<relianoid_server>:444/api/v4.0/api.cgi/interfaces/virtual
zcli network-virtual list
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 |
---|---|---|
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. |
+ in EE version:
Field | Type | Description |
---|---|---|
alias | String | It is a nick to help to identify the interface. Alias |
Retrieve virtual interface
Retrieve virtual interface
Request example:
curl -k -X GET -H "ZAPI_KEY: <ZAPI_KEY_STRING>"
https://<relianoid_server>:444/api/v4.0/api.cgi/interfaces/virtual/eth0:virtiface
zcli network-virtual get eth0:vip1
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 |
---|---|---|
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. |
+ in EE version:
Field | Type | Description |
---|---|---|
alias | String | It is a nick to help to identify the interface. Alias |
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://<relianoid_server>:444/api/v4.0/api.cgi/interfaces/virtual
zcli network-virtual create -name eth0:virtiface -ip 192.168.100.41
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://<relianoid_server>:444/api/v4.0/api.cgi/interfaces/virtual/eth0:virtiface
zcli network-virtual set eth0:virtiface -ip 192.168.131.155
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://<relianoid_server>:444/api/v4.0/api.cgi/interfaces/virtual/eth0:virtiface
zcli network-virtual delete 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://<relianoid_server>:444/api/v4.0/api.cgi/interfaces/virtual/eth0:virtiface/actions
zcli network-virtual stop eth0:virtiface
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, RELIANOID 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:
Network interface support in the base drivers for retrieving the speed and duplex of each slave.
A switch that supports IEEE 802.3ad Dynamic link aggregation. Most switches will require some type of configuration to enable 802.3ad mode.
Adaptive transmit load balancing: Channel bonding that does not require any special switch support. The outgoing traffic is distributed according to the current load (computed relative to the speed) on each slave. Incoming traffic is received by the current slave. If the receiving slave fails, another slave takes over the MAC address of the failed receiving slave.
Pre-requisite:
Base driver support for retrieving the speed of each slave.
Adaptive load balancing: Includes Adaptive transmit load balancing plus receive load balancing for IPV4 traffic, and does not require any special switch support. The receive load balancing is achieved by ARP negotiation. The bonding driver intercepts the ARP Replies sent by the local system on their way out and overwrites the source hardware address with the unique hardware address of one of the slaves in the bonding such that different peers use different hardware addresses for the server.
List Bonding interfaces
List Bonding interfaces
Request example:
curl -k -X GET -H "ZAPI_KEY: <ZAPI_KEY_STRING>"
https://<relianoid_server>:444/api/v4.0/api.cgi/interfaces/bonding
zcli network-bonding list
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://<relianoid_server>:444/api/v4.0/api.cgi/interfaces/bonding/bondiface
zcli network-bonding get 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://<relianoid_server>:444/api/v4.0/api.cgi/interfaces/bonding
zcli network-bonding create -slave eth3,eth2 -name bondiface -mode balance-rr
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://<relianoid_server>:444/api/v4.0/api.cgi/interfaces/bonding/bondiface
zcli network-bonding set bondiface -ip 192.168.100.121 -netmask 255.255.255.0 -gateway 192.168.100.1 -mac 86:2f:0e:9a:30:14
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://<relianoid_server>:444/api/v4.0/api.cgi/interfaces/bonding/bondiface
zcli network-bonding delete 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://<relianoid_server>:444/api/v4.0/api.cgi/interfaces/bonding/bondiface/actions
zcli network-bond start bondiface
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://<relianoid_server>:444/api/v4.0/api.cgi/interfaces/bonding/bondiface/slaves
zcli network-bonding-slave add bondiface -name eth4
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://<relianoid_server>:444/api/v4.0/api.cgi/interfaces/bonding/bondiface/slaves/eth2
zcli network-bonding-slave remove bondiface 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://<relianoid_server>:444/api/v4.0/api.cgi/interfaces/floating
zcli network-floating list
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://<relianoid_server>:444/api/v4.0/api.cgi/interfaces/floating/eth0
zcli network-floating get 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://<relianoid_server>:444/api/v4.0/api.cgi/interfaces/floating/eth0
zcli network-floating set eth0 -floating_ip 192.168.100.199
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://<relianoid_server>:444/api/v4.0/api.cgi/interfaces/floating/eth0
zcli network-floating delete 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://<relianoid_server>:444/api/v4.0/api.cgi/aliases/backends
zcli network-alias-backend list
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 an alias
Create an alias
Request example:
curl -k -X POST -H 'Content-Type: application/json' -H "ZAPI_KEY: <ZAPI_KEY_STRING>"
-d '{"id":"eth0","alias":"management"}'
https://<relianoid_server>:444/api/v4.0/api.cgi/aliases/interfaces
zcli network-alias-interface set eth0 -alias management
POST /aliases/<backends|interfaces>
The backend or interfaces kind of object which will receive the alias.
Request parameters
Field | Type | Description | Required |
---|---|---|---|
alias | String | It is the nick for the element id sent in the URI. | true |
id | String | It is the backend IP or the interface name. | true |
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.
Modify an alias
Modify an alias
Request example:
curl -k -X PUT -H 'Content-Type: application/json' -H "ZAPI_KEY: <ZAPI_KEY_STRING>"
-d '{"alias":"gateway"}'
https://<relianoid_server>:444/api/v4.0/api.cgi/aliases/interfaces/eth0
zcli network-alias-interface set eth0 -alias gateway
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 | Required |
---|---|---|---|
alias | String | It is the nick for the element id sent in the URI. | true |
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://<relianoid_server>:444/api/v4.0/api.cgi/aliases/interfaces/eth0
zli network-alias-interface delete 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.
Network - Routing
This module is available from zapi version 4.0.1.
This module manages the routes for traffic is going through or from the load balancer. This process calculates the output interface depends on the packet source and the packet destination. For this task, the load balancer uses two kinds of objects rules and tables.
The first step is looking for a rule where the packet source matches, once the rule is found, the packet outcoming interface is looking for in the table that rule defined. The interface is token of the route which matches with packet destination.
List routing rules
List routing rules
Request example:
curl -k -X GET -H "ZAPI_KEY: <ZAPI_KEY_STRING>"
https://<relianoid_server>:444/api/v4.0/api.cgi/routing/rules
zcli network-routing-rule list
GET /routing/rules
List the routing rules of the load balancer. Routing rules are used to get the interface table depend on the source packet IP
Response example:
{
"description" : "List routing rules",
"params" : [
{
"id" : 1024,
"not" : "true",
"from" : "10.10.10.0/24",
"priority" : 30000,
"table" : "table_eth1",
"type" : "user"
},
{
"table" : "local",
"type" : "system",
"id" : 0,
"priority" : 0,
"from" : "all"
},
{
"id" : 0,
"priority" : 31000,
"from" : "10.3.0.0/24",
"table" : "205",
"type" : "system"
},
{
"type" : "system",
"table" : "table_eth1",
"priority" : 31000,
"from" : "4.4.4.0/24",
"id" : 0
},
{
"type" : "system",
"table" : "main",
"priority" : 32766,
"from" : "all",
"id" : 0
}
]
}
Response parameters
The response will be a JSON list with all the routing rules in the system. Each rule is an object with the following parameters:
Field | Type | Description |
---|---|---|
id | Number | It is the unique identifier used for routing rules. |
not | String | This field is used combined with the parameter from to negate the match result. This parameter is a boolean string with the value true to enabled it or with the value false if the match result does not be negated. |
from | String | It is the source IP or networking segment used to match with the source IP of the packet. |
priority | Number | It is the rule priority, a minor value of priority is a high priority. |
table | String | It is the interface table used to route if the packet source IP matches with parameter from. |
type | String | It is the kind of rule, this field can have the values: farm is a route used to route traffic of an l4xnat farm, user is a rule that was created by the load balancer administrator or system is a rule generated automatically for the system. |
Create Routing Rule
Create Routing Rule
Request example:
curl -k -X POST -H 'Content-Type: application/json' -H "ZAPI_KEY: <ZAPI_KEY_STRING>"
-d '{"table":"table_eth1","not":"true","priority":"30000","from":"192.168.0.0/16"}'
https://<relianoid_server>:444/api/v4.0/api.cgi/routing/rules
zcli network-routing-rule -table table_eth1 -not true -priority 30000 -from 192.168.0.0/16
POST /routing/rules
Create a routing rule.
Request parameters
Field | Type | Description | Required |
---|---|---|---|
not | String | This field is used combined with the parameter from to negate the match result. This parameter is a boolean string with the value true to enabled it or with the value false if the match result does not be negated. | |
from | String | It is the source IP or networking segment used to match with the source IP of the packet. | true |
priority | Number | It is the rule priority, a minor value of priority is a high priority. The created rules must have a value between 29000 and 30999 | |
table | String | It is the interface table used to route if the packet source IP matches with parameter from. | true |
Response example:
{
"description" : "Create a routing rule",
"params" : [
{
"not" : "true",
"id" : 1024,
"from" : "192.168.0.0/16",
"priority" : 30000,
"table" : "table_eth1",
"type" : "user"
},
{
"table" : "table_eth0",
"type" : "system",
"id" : 0,
"priority" : 32765,
"from" : "192.168.100.0/24"
},
{
"from" : "all",
"priority" : 32766,
"id" : 0,
"type" : "system",
"table" : "main"
},
{
"id" : 0,
"priority" : 32767,
"from" : "all",
"table" : "default",
"type" : "system"
}
]
}
Response parameters
The response will be a JSON object with all the routes rules of the system. Each route is an object with the parameters:
Field | Type | Description |
---|---|---|
id | Number | It is the unique identifier used for routing rules. |
not | String | This field is used combined with the parameter from to negate the match result. This parameter is a boolean string with the value true to enabled it or with the value false if the match result does not be negated. |
from | String | It is the source IP or networking segment used to match with the source IP of the packet. |
priority | Number | It is the rule priority, a minor value of priority is a high priority. |
table | String | It is the interface table used to route if the packet source IP matches with parameter from. |
type | String | It is the kind of rule, this field can have the values: farm is a route used to route traffic of an l4xnat farm, user is a rule that was created by the load balancer administrator or system is a rule generated automatically for the system. |
Modify Routing Rule
Modify Routing Rule
Request example:
curl -k -X PUT -H 'Content-Type: application/json' -H "ZAPI_KEY: <ZAPI_KEY_STRING>"
-d '{"table":"table_eth1","from":"10.10.10.0/24","priority":"30000","not":"false"}'
https://<relianoid_server>:444/api/v4.0/api.cgi/routing/rules/1024
zcli network-routing-rule set 1024 -table table_eth1 -from 10.10.10.0/24 -priority 30000 -not false
PUT /routing/rules/<id>
Modify the parameters of a routing rule.
The id URI parameter is the rule unique identifier.
The rules of type user are the unique that can be modified
Request parameters
Field | Type | Description | Required |
---|---|---|---|
not | String | This field is used combined with the parameter from to negate the match result. | |
from | String | It is the source IP or networking segment used to match with the source IP of the packet. This parameter is a boolean string with the value true to enabled it or with the value false if the match result does not be negated. | true |
priority | Number | It is the rule priority, a minor value of priority is a high priority. The created rules must have a value between 29000 and 30999 | |
table | String | It is the interface table used to route if the packet source IP matches with parameter from. | true |
Response example:
{
"description" : "Modify a routing rule",
"params" : [
{
"not" : "true",
"id" : 1024,
"priority" : 30000,
"from" : "10.10.10.0/24",
"table" : "table_eth1",
"type" : "user"
},
{
"id" : 0,
"from" : "4.4.4.0/24",
"priority" : 31000,
"table" : "table_eth1",
"type" : "system"
},
{
"table" : "table_eth2",
"type" : "system",
"id" : 0,
"from" : "5.5.5.0/24",
"priority" : 31000
},
{
"type" : "system",
"table" : "table_eth0",
"from" : "192.168.100.0/24",
"priority" : 32765,
"id" : 0
},
]
}
Response parameters
The response will be a JSON object with all the routes rules of the system. Each route is an object with the parameters:
Field | Type | Description |
---|---|---|
id | Number | It is the unique identifier used for routing rules. |
not | String | This field is used combined with the parameter from to negate the match result. This parameter is a boolean string with the value true to enabled it or with the value false if the match result does not be negated. |
from | String | It is the source IP or networking segment used to match with the source IP of the packet. |
priority | Number | It is the rule priority, a minor value of priority is a high priority. |
table | String | It is the interface table used to route if the packet source IP matches with parameter from. |
type | String | It is the kind of rule, this field can have the values: farm is a route used to route traffic of an l4xnat farm, user is a rule that was created by the load balancer administrator or system is a rule generated automatically for the system. |
Delete Routing Rule
Delete Routing Rule
Request example:
curl -k -X DELETE -H "ZAPI_KEY: <ZAPI_KEY_STRING>"
https://<relianoid_server>:444/api/v4.0/api.cgi/routing/rules/1024
zcli network-routing-rule remove 1024
DELETE /routing/rules/<id>
Delete a routing rule.
The id URI parameter is the rule unique identifier.
Response example:
{
"message" : "The routing rule '1024' has been deleted successfully.",
"description" : "Delete the routing rule '1024'"
}
List routing tables
List routing tables
Request example:
curl -k -X GET -H "ZAPI_KEY: <ZAPI_KEY_STRING>"
https://<relianoid_server>:444/api/v4.0/api.cgi/routing/tables
zcli network-routing-table list
GET /routing/tables
List the routing tables that the load balancer manages.
The main table is global for all interfaces. It contains default routes for all interfaces that will be used if no rules match with the packet. Each interface table manages the routes for the outcoming traffic of that interface.
Response example:
{
"description" : "List routing tables",
"params" : [
"main",
"table_eth0",
"table_eth1",
"table_eth2",
"table_eth3"
]
}
Response parameters
The response will be a JSON object with the params key that contains a list with the tables that exist in the system.
List Routes of a table
List routing rules
Request example:
curl -k -X GET -H "ZAPI_KEY: <ZAPI_KEY_STRING>"
https://<relianoid_server>:444/api/v4.0/api.cgi/routing/tables/table_eth2
zcli network-routing-table get table_eth2
GET /routing/tables/<table>
List the routes entries that an interface table manages. Those entries are used to match the packet destination IP. The outcoming interface for the packet will be the first interface that will match with an entry of the table.
Response example:
{
"description" : "Get the routing table 'table_eth2'",
"params" : [
{
"to" : "84.1.21.5",
"via" : "4.4.4.45",
"priority" : 2,
"raw" : "84.1.21.5 dev eth1 src 4.4.4.4 via 4.4.4.45 metric 2 table table_eth2",
"id" : 1024,
"source" : "4.4.4.4",
"type" : "user",
"interface" : "eth1"
},
{
"priority" : 10,
"raw" : "5.5.5.0/24 dev eth2 scope link src 5.5.5.5 initcwnd 10 initrwnd 10 table table_eth2",
"interface" : "eth2",
"source" : "5.5.5.5",
"type" : "system",
"to" : "5.5.5.0/24",
"via" : ""
},
{
"via" : "",
"to" : "192.168.100.0/24",
"interface" : "eth0",
"type" : "system",
"source" : "192.168.100.241",
"raw" : "192.168.100.0/24 dev eth0 scope link src 192.168.100.241 initcwnd 10 initrwnd 10 table table_eth2",
"priority" : 10
}
]
}
Response parameters
The response will be a JSON object with the key params and a list of the routes that contains the table.
Field | Type | Description |
---|---|---|
raw | String | It is the routing entry with the IP route format. |
priority | Number | It is the priority in which the route will be examined. A lower value is more priority. This field has to have a value between 1 and 10. |
interface | String | It is the outcoming interface used if the route matches. |
source | String | It is the IP used to masquerade the packet. This source has to exist in the load balancer as a virtual interface. |
type | String | It is the type of route. The routes can be of type system that are created and managed automatically by the system, or user when the route was created by a load balancer user. Checking the unmanage feature to remove a system route. |
to | String | It is de match condition. If the packet destination IP matches with it the route is successful. |
via | String | It is the next hop of the packet. It is used as a gateway. This IP has to be reached from the interface networking segment. |
id | Number | It is the unique identifier of the route. This parameter is used to modify or delete the route and only is available in routes of type user. |
Create Routing Entry
Create Routing Entry
Request example:
curl -k -X POST -H 'Content-Type: application/json' -H "ZAPI_KEY: <ZAPI_KEY_STRING>"
-d '{"source":"4.4.4.4","via":"4.4.4.45","interface":"eth1","priority":2,"to":"84.1.21.5"}'
https://<relianoid_server>:444/api/v4.0/api.cgi/routing/tables/table_eth2/routes
zcli network-routing-table add table_eth2 -source 4.4.4.4 -via 4.4.4.45 -interface eth1 -priority 2 -to 84.1.21.5
POST /routing/tables/<table>/routes
Create a route for an interface.
The table URI parameter is the interface table where the route will be added.
Request parameters
Field | Type | Description | Required |
---|---|---|---|
raw | String | It is the routing entry with the IP route format. If this parameter is used, the others will be avoided. | |
to | String | It is de match condition. If the packet destination IP matches with it the route is successful. | It is required when raw is not sent |
priority | Number | It is the priority in which the route will be examined. A lower value is more priority. This field has to have a value between 1 and 10. | |
interface | String | It is the outcoming interface used if the route matches. | |
source | String | It is the IP used to masquerade the packet. This source has to exist in the load balancer as a virtual interface. | |
via | String | It is the next hop of the packet. It is used as a gateway. This IP has to be reached from the interface networking segment. |
Response example:
{
"description" : "Create a routing entry in the table 'table_eth2'",
"params" : [
{
"to" : "84.1.21.5",
"via" : "4.4.4.45",
"priority" : 2,
"raw" : "84.1.21.5 dev eth1 src 4.4.4.4 via 4.4.4.45 metric 2 table table_eth2",
"id" : 1024,
"source" : "4.4.4.4",
"type" : "user",
"interface" : "eth1"
},
{
"raw" : "default via 5.5.5.1 dev eth2 initcwnd 10 initrwnd 10 table table_eth2",
"priority" : 10,
"source" : "",
"type" : "system",
"interface" : "eth2",
"to" : "default",
"via" : "5.5.5.1"
},
{
"priority" : 10,
"raw" : "4.4.4.0/24 dev eth1 scope link src 4.4.4.4 initcwnd 10 initrwnd 10 table table_eth2",
"source" : "4.4.4.4",
"type" : "system",
"interface" : "eth1",
"to" : "4.4.4.0/24",
"via" : ""
},
]
}
Response parameters
The response will be a JSON object with the key params and a list of the routes that contains the table.
Field | Type | Description |
---|---|---|
priority | Number | It is the priority in which the route will be examined. A lower value is more priority. This field has to have a value between 1 and 10. |
raw | String | It is the routing entry with the IP route format. |
interface | String | It is the outcoming interface used if the route matches. |
source | String | It is the IP used to masquerade the packet. This source has to exist in the load balancer as a virtual interface. |
type | String | It is the type of route. The routes can be of type system that are created and managed automatically by the system, or user when the route was created by a load balancer user. Checking the unmanage feature to remove a system route. |
to | String | It is de match condition. If the packet destination IP matches with it the route is successful. |
via | String | It is the next hop of the packet. It is used as a gateway. This IP has to be reached from the interface networking segment. |
id | Number | It is the unique identifier of the route. This parameter is used to modify or delete the route and only is available in routes of type user. |
Modify a Route Entry
Modify a Route Entry
Request example:
curl -k -X PUT -H 'Content-Type: application/json' -H "ZAPI_KEY: <ZAPI_KEY_STRING>"
-d '{"priority":2,"source":"4.4.4.4","interface":"eth1","to":"71.71.71.0/24","via":"4.4.4.45"}'
https://<relianoid_server>:444/api/v4.0/api.cgi/routing/tables/table_eth2/routes/1024
zcli network-routing-table -id 1024 -priority 2 -source 4.4.4.4 -interface eth1 -to 71.71.71.0/24 -via 4.4.4.45
PUT /routing/tables/<table>/routes/<id>
Modify the parameters of a route entry.
The table URI parameter is the interface table of the route that will be modified. The id URI parameter is the route unique identifier of the route that will be modified.
Request parameters
Field | Type | Description |
---|---|---|
raw | String | It is the routing entry with the IP route format. If this parameter is used, the others will be avoided. |
priority | Number | It is the priority in which the route will be examined. A lower value is more priority. This field has to have a value between 1 and 10. |
interface | String | It is the outcoming interface used if the route matches. |
source | String | It is the IP used to masquerade the packet. This source has to exist in the load balancer as a virtual interface. |
to | String | It is de match condition. If the packet destination IP matches with it the route is successful. |
via | String | It is the next hop of the packet. It is used as a gateway. This IP has to be reached from the interface networking segment. |
Response example:
{
"description" : "Modify a routing entry in the table 'table_eth2'",
"params" : [
{
"to" : "71.71.71.0/24",
"via" : "4.4.4.45",
"raw" : "71.71.71.0/24 dev eth1 src 4.4.4.4 via 4.4.4.45 metric 2 table table_eth2",
"priority" : 2,
"id" : 1024,
"type" : "user",
"source" : "4.4.4.4",
"interface" : "eth1"
},
{
"raw" : "default via 5.5.5.1 dev eth2 initcwnd 10 initrwnd 10 table table_eth2",
"priority" : 10,
"interface" : "eth2",
"source" : "",
"type" : "system",
"to" : "default",
"via" : "5.5.5.1"
},
{
"via" : "",
"to" : "4.4.4.0/24",
"interface" : "eth1",
"source" : "4.4.4.4",
"type" : "system",
"priority" : 10,
"raw" : "4.4.4.0/24 dev eth1 scope link src 4.4.4.4 initcwnd 10 initrwnd 10 table table_eth2"
},
]
}
Response parameters
The response will be a JSON object with the key params and a list of the routes that contains the table.
Field | Type | Description |
---|---|---|
priority | Number | It is the priority in which the route will be examined. A lower value is more priority. This field has to have a value between 1 and 10. |
raw | String | It is the routing entry with the IP route format. |
interface | String | It is the outcoming interface used if the route matches. |
source | String | It is the IP used to masquerade the packet. This source has to exist in the load balancer as a virtual interface. |
type | String | It is the type of route. The routes can be of type system that are created and managed automatically by the system, or user when the route was created by a load balancer user. Checking the unmanage feature to remove a system route. |
to | String | It is de match condition. If the packet destination IP matches with it the route is successful. |
via | String | It is the next hop of the packet. It is used as a gateway. This IP has to be reached from the interface networking segment. |
id | Number | It is the unique identifier of the route. This parameter is used to modify or delete the route and only is available in routes of type user. |
Delete a Route Entry
Delete a Route Entry
Request example:
curl -k -X DELETE -H "ZAPI_KEY: <ZAPI_KEY_STRING>"
https://<relianoid_server>:444/api/v4.0/api.cgi/routing/tables/table_eth2/routes/1024
zcli network-routing-table remove table_eth2 1024
DELETE /routing/tables/<table>/routes/<id>
Delete a route of an interface table.
The table URI parameter is the interface table from which the route will be deleted. The id URI parameter is the route unique identifier of the route that will be deleted.
Response example:
{
"description" : "Delete the routing entry '1024' from the table 'table_eth2'",
"message" : "The routing rule '1024' has been deleted successfully."
}
List of Interfaces Unmanaged in a Table
List of Interfaces Unmanagned in a Table
Request example:
curl -k -X GET -H "ZAPI_KEY: <ZAPI_KEY_STRING>"
https://<relianoid_server>:444/api/v4.0/api.cgi/routing/tables/table_eth1/unmanaged
zcli network-routing-table-unmanaged get table_eth1
GET /routing/tables/<table>/unmanaged
This feature is used to avoid traffic from an interface that can go outcoming for another one.
table is the routing table of the incoming interface.
List the interfaces and if they can be used to outcoming the traffic.
Response example:
{
"params" : [
{
"unmanaged" : "false",
"interface" : "eth3"
},
{
"unmanaged" : "false",
"interface" : "eth0"
}
],
"description" : "Get the list of interfaces that cannot manage traffic when traffic incoming through the table 'table_eth1'"
}
Response parameters
The response will be a JSON object with the key params that contains a list of objects with the following parameters.
Field | Type | Description |
---|---|---|
interface | String | It is the name of the output interface. |
unmanaged | String | It is the routing status of the interface. If it has the value false, this interface can be reached from the table; if it has the value true, it won't outcoming traffic from the table. |
Add an interface to the list of unmanaged
Unmanage an Interface
Request example:
curl -k -X POST -H 'Content-Type: application/json' -H "ZAPI_KEY: <ZAPI_KEY_STRING>"
-d '{"interface":"eth2"}'
https://<relianoid_server>:444/api/v4.0/api.cgi/routing/tables/table_eth1/unmanaged
zcli network-routing-table-unmanaged add table_eth1 interface eth0
POST /routing/tables/<table>/unmanaged
Disable an interface for outcoming traffic.
The table URI parameter is the routing table name from which a route will not be reacheable. If table has the value "*" (asterisk), the interface will not be accessible from any table.
Request parameters
Field | Type | Description | Required |
---|---|---|---|
interface | String | It is the interface that won't be able to route from the table. | true |
Response example:
{
"description" : "Do not route traffic through an interface for the table 'table_eth1'",
"message" : "The interface 'eth2' is not accesible from the table 'table_eth1'"
}
Remove an interface from the list of unmanaged
Manage a Routing Table
Request example:
curl -k -X DELETE -H "ZAPI_KEY: <ZAPI_KEY_STRING>"
https://<relianoid_server>:444/api/v4.0/api.cgi/routing/tables/table_eth1/unmanaged/eth2
zcli network-routing-table-unmanaged remove table_eth1 eth2
DELETE /routing/tables/<table>/unmanaged/<interface>
Allow the interface will be visibility from another interface table
The table URI parameter is the interface table that is being modified. If table has the value "*" (asterisk), the interface will be managed from all tables. The interface URI parameter is the interface that will be allowed for the table table.
Response example:
{
"description" : "Enable an interface as possible route path from the table 'table_eth1'",
"message" : "The interface 'eth2' is now accesible from the table 'table_eth1'"
}
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://<relianoid_server>:444/api/v4.0/api.cgi/monitoring/fg
zcli farmguardian list
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",
"backend_alias" : "false"
},
{
"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",
"backend_alias" : "true"
},
{
"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",
"backend_alias" : "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. |
+ in EE version:
Field | Type | Description |
---|---|---|
backend_alias (from 4.0.1) | String | If this parameter has the value false, the backend host will be the backend IP. The alias of the backend will be used as host if this parameter has the value true, the alias has to be defined and the load balancer should be able to resolve it. |
Retrieve a FarmGuardian
Retrieve a FarmGuardian
Request example:
curl -k -X GET -H "ZAPI_KEY: <ZAPI_KEY_STRING>"
https://<relianoid_server>:444/api/v4.0/api.cgi/monitoring/fg/check_tcp
zcli farmguardian get 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" : 10,
"log" : "false",
"name" : "check_tcp",
"template" : "true",
"backend_alias" : "false",
"timeout" : 5
}
}
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. This is the time from when the last backend in the list is tested until the first backend is tested again. |
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. |
+ in EE version:
Field | Type | Description |
---|---|---|
backend_alias (from 4.0.1) | String | If this parameter has the value false, the backend host will be the backend IP. The alias of the backend will be used as host if this parameter has the value true, the alias has to be defined and the load balancer should be able to resolve it. |
timeout (from 4.0.2) | Number | Timeout for each backend. After this time during the backend test, it will be considered down. By default, timeout is equal to interval. |
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://<relianoid_server>:444/api/v4.0/api.cgi/monitoring/fg
zcli farmguardian create -name check_tcp-cut_conns -copy_from check_tcp
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 |
+ in CE version:
Field | Type | Description |
---|---|---|
parent | String | It is the FarmGuardian used as template to create the new FarmGuardian. If this field is not sent, the new FarmGuardian is created in blank. |
+ in EE version:
Field | Type | Description |
---|---|---|
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",
"backend_alias" : "false",
"timeout" : 5
}
}
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. This is the time from when the last backend in the list is tested until the first backend is tested again. |
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. |
+ in EE version:
Field | Type | Description |
---|---|---|
backend_alias (from 4.0.1) | String | If this parameter has the value false, the backend host will be the backend IP. The alias of the backend will be used as host if this parameter has the value true, the alias has to be defined and the load balancer should be able to resolve it. |
timeout (from 4.0.2) | Number | Timeout for each backend. After this time during the backend test, it will be considered down. By default, timeout is equal to interval. |
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://<relianoid_server>:444/api/v4.0/api.cgi/monitoring/fg/custom-tcp
zcli farmguardian set custom-tcp -interval 7 -log true -description 'TCP check to the port 80' -command 'check_tcp -p 80 -H HOST' -cut_conns false
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. This is the time from when the last backend in the list is tested until the first backend is tested again. | |
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. |
+ in EE version:
Field | Type | Description |
---|---|---|
backend_alias (from 4.0.1) | String | If this parameter has the value false, the backend host will be the backend IP. The alias of the backend will be used as host if this parameter has the value true, the alias has to be defined and the load balancer should be able to resolve it. |
timeout (from 4.0.2) | Number | Timeout for each backend. After this time during the backend test, it will be considered down. By default, timeout is equal to interval. |
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",
"backend_alias" : "false",
"timeout" : 7
}
}
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. This is the time from when the last backend in the list is tested until the first backend is tested again. |
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. |
+ in EE version:
Field | Type | Description |
---|---|---|
backend_alias (from 4.0.1) | String | If this parameter has the value false, the backend host will be the backend IP. The alias of the backend will be used as host if this parameter has the value true, the alias has to be defined and the load balancer should be able to resolve it. |
timeout (from 4.0.2) | Number | Timeout for each backend. After this time during the backend test, it will be considered down. By default, timeout is equal to interval. |
Delete a FarmGuardian
Delete a FarmGuardian
Request example:
curl -k -X DELETE -H 'Content-Type: application/json' -H "ZAPI_KEY: <ZAPI_KEY_STRING>"
https://<relianoid_server>:444/api/v4.0/api.cgi/monitoring/fg/custom-tcp
zcli farmguardian delete 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 RELIANOID load balancer status.
Show system statistics
Show system statistics
Request example:
curl -k -X GET -H "ZAPI_KEY: <ZAPI_KEY_STRING>"
https://<relianoid_server>:444/api/v4.0/api.cgi/stats
zcli statistics-system get
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://<relianoid_server>:444/api/v4.0/api.cgi/stats/system/network
zcli statistic-network get
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://<relianoid_server>:444/api/v4.0/api.cgi/stats/system/network/interfaces
zcli statistics-network get
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 |
---|---|---|
nic | Object[] | NIC interface statistics. |
+ in EE version:
Field | Type | Description |
---|---|---|
bond | Object[] | Bond 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://<relianoid_server>:444/api/v4.0/api.cgi/stats/system/memory
zcli statistics-system get -filter 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://<relianoid_server>:444/api/v4.0/api.cgi/stats/system/load
zcli statistics-system get -filter 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://<relianoid_server>:444/api/v4.0/api.cgi/stats/system/cpu
zcli statistics-system get -filter 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://<relianoid_server>:444/api/v4.0/api.cgi/stats/system/connections
zcli statistics-network-connections get
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://<relianoid_server>:444/api/v4.0/api.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://<relianoid_server>:444/api/v4.0/api.cgi/stats/farms
statistics-farm list
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 in maintenance mode; problem, the farm is up and there are some backends that that are unreachable, but at least one backend has the "up" status; maintenance, the farm is up and there are backends in up status, but at least 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://<relianoid_server>:444/api/v4.0/api.cgi/stats/farms/farmname
zcli statistic-farm list
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" : [
{
"alias": null,
"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"
"backend_ip" : "192.168.0.168"
"backend_port" : 80
"service" : "srv1",
"session" : "192.168.0.186",
"ttl" : "1m28s0ms"
}
],
"total_sessions" : 1
}
Response parameters in HTTP farms
Field | Type | Description |
---|---|---|
backends | Object[] | Show information about backends. |
sessions | Object[] | Show information about sessions. |
+ in EE version:
Field | Type | Description |
---|---|---|
total_sessions | Number | From version 4.0.2. Displays the total number of registered 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. |
+ in EE version:
Field | Type | Description |
---|---|---|
alias | String | It is a nick to help to identify the backend. Alias |
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. |
ttl | String | From version 4.0.2. Time remaining until the session ends |
backend_ip | String | From version 4.0.2. Backend Ip assigned to the client. |
backend_port | String | From version 4.0.2. Backend port assigned to the client. |
Response example for GSLB farm (for EE version ):
{
"backends" : [
{
"alias": null,
"id" : 1,
"ip" : "127.0.0.1",
"port" : 53,
"service" : "service1",
"status" : "down"
},
{
"alias": null,
"id" : 2,
"ip" : "192.168.55.40",
"port" : 53,
"service" : "service1",
"status" : "down"
},
{
"alias": null,
"id" : 4,
"ip" : "192.135.10.2",
"port" : 53,
"service" : "service1",
"status" : "down"
},
{
"alias": null,
"id" : 1,
"ip" : "127.0.0.1",
"port" : 80,
"service" : "prioServ",
"status" : "down"
},
{
"alias": null,
"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,
"edns_cookie_formerr" : 0,
"edns_cookie_init" : 0,
"edns_cookie_ok" : 0,
"edns_do" : 0,
"formerr" : 0,
"noerror" : 0,
"notimp" : 0,
"nxdomain" : 0,
"refused" : 0,
"v6" : 0
},
"server" : {
"acceptfail" : 0,
"close_c" : 0,
"close_s_err" : 0,
"close_s_kill" : 0,
"close_s_ok" : 0,
"conns" : 0,
"dso_estab" : 0,
"dso_protoerr" : 0,
"dso_typeni" : 0,
"proxy" : 0,
"proxy_fail" : 0,
"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 |
---|---|---|
alias | String | It is a nick to help to identify the backend. Alias |
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. |
edns_cookie_bad | Number | Cookie option contained client+server cookies. |
edns_cookie_formerr | Number | Cookie option had RFC-illegal cookie data length, causing FORMERR rejection of the request. |
edns_cookie_init | Number | Cookie option contained just a client-side cookie value but no server cookie value. |
edns_cookie_ok | Number | Cookie option contained a correct client+server cookie combo we cryptographically validated. |
edns_cookie_do | Number | EDNS requests which had the DO (DNSSEC OK) bit set. |
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 |
---|---|---|
acceptfail | Number | Count of all TCP non-trivial failure returns. |
close_c | Number | Count of TCP connections closed cleanly by the client. |
close_s_err | Number | Count of TCP connections closed by the server due to an error such as recvfail , sendfail , or dropped from the general stats. |
close_s_kill | Number | Count of TCP connections closed by the server, which were killed early to make room for a new client when max_clients_per_thread was reached. |
close_s_ok | Number | Count of TCP connections closed cleanly by the server, usually due to an idle timeout being reached or during thread shutdown, etc. |
conns | Number | Count of TCP connections we accepted (excludes extremely early failures, e.g. accept() itself returning an error). |
dso_estab | Number | TCP connections which established an RFC 8490 DSO session (can only happen up to once per connection). |
dso_protoerr | Number | TCP DSO sessions terminated un-gracefully due to client protocol violation (can only happen up to once per DSO session). |
dso_typeni | Number | Unrecognized DSO Request type received over TCP (could be with or without an established DSO session, and many times per connection/session). |
proxy | Number | TCP conns initiated on PROXY protocol listeners (also incs conns ). |
proxy_fail | Number | TCP PROXY conns killed for failure to parse an acceptable PROXY protocol header (also incs close_s_err ). |
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" : [
{
"alias" : null,
"established" : 5,
"id" : 1,
"ip" : "192.168.5.40",
"pending" : 0,
"port" : "8080",
"status" : "maintenance",
"max_conns" : 5,
"priority" : 1,
"weight" : 1
},
{
"alias" : null,
"established" : null,
"id" : 3,
"ip" : "192.5.1.1",
"pending" : 0,
"port" : "787",
"status" : "down",
"max_conns" : 5,
"priority" : 1,
"weight" : 1
},
{
"alias" : null,
"established" : 1,
"id" : 5,
"ip" : "192.168.5.100",
"pending" : 0,
"port" : "8080",
"status" : "up",
"max_conns" : 5,
"priority" : 1,
"weight" : 1
}
],
"description" : "List farm stats",
"sessions" : [
{
"client": 0,
"id" : 5,
"backend_ip" : "192.168.5.100",
"backend_port" : "8080",
"session" : "192.168.5.100",
"ttl" : "1m51s564ms",
"type" : "dynamic"
}
],
"total_sessions" : 1
}
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. |
weight | Number | It’s the weight value for the current backend. The possible values are from 1 to 9. |
priority (from 4.0.1) | Number | It’s the priority value for the current real server. Backend with lower priority value will be ready to receive connections before than others with higher priority. Default value null, a priority value 1 is used. The possible values are from 1 to 9 |
connection_limit (from 4.0.2) | Number | The maximum number of established connection per backend. With a value of 0, there will not be a limit in the backend. The client will receive a 503 error if there aren’t available backends.(In CE version 'max_conns') |
+ in EE version:
Field | Type | Description |
---|---|---|
alias | String | It is a nick to help to identify the backend. Alias |
Session object:
Field | Type | Description |
---|---|---|
client | Number | Session secuential identifier. |
id | Number | Backend unique identifier where the client is assigned. |
session | String | Session unique identifier. It is the client IP. |
ttl | String | From version 4.0.2. Time remaining until the session ends |
backend_ip | String | From version 4.0.2. Backend ip assigned to the client. |
backend_port | Number | From version 4.0.2. Backend port assigned to the client. |
+ in EE version:
Field | Type | Description |
---|---|---|
type | String | Values are: static or dynamic. Static if the session was made manually and dynamic if the session was made automatically. |
+ in CE version: Field | Type | Description ------------ | ------------- | -------------- client | String | Client unique identifier.
Response parameters in datalink farms
Datalink farms statistics is not available actually.
Show module status
Show module status
Request example:
curl -k -X GET -H "ZAPI_KEY: <ZAPI_KEY_STRING>"
https://<relianoid_server>:444/api/v4.0/api.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://<relianoid_server>:444/api/v4.0/api.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 at least 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://<relianoid_server>:444/api/v4.0/api.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://<relianoid_server>:444/api/v4.0/api.cgi/graphs/farms/httpweb
Request example for an interface:
curl -k -X GET -H "ZAPI_KEY: <ZAPI_KEY_STRING>"
https://<relianoid_server>:444/api/v4.0/api.cgi/graphs/interfaces/eth3
Request example for a disk:
curl -k -X GET -H "ZAPI_KEY: <ZAPI_KEY_STRING>"
https://<relianoid_server>:444/api/v4.0/api.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://<relianoid_server>:444/api/v4.0/api.cgi/graphs/farms/httpweb/daily
Request example for an interface:
curl -k -X GET -H "ZAPI_KEY: <ZAPI_KEY_STRING>"
https://<relianoid_server>:444/api/v4.0/api.cgi/graphs/interfaces/eth3/monthly
Request example for a disk:
curl -k -X GET -H "ZAPI_KEY: <ZAPI_KEY_STRING>"
https://<relianoid_server>:444/api/v4.0/api.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 RELIANOID 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://<relianoid_server>:444/api/v4.0/api.cgi/ipds/package
zcli ipds-package get
GET /ipds/package
Retrieve the relianoid-ipds package information. This package contains updated rules for each IPDS module.
Response example:
{
"description" : "relianoid-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://<relianoid_server>:444/api/v4.0/api.cgi/ipds/package/actions
zcli ipds-package upgrade
Response example:
{
"desc" : "Execute an action over the relianoid-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://<relianoid_server>:444/api/v4.0/api.cgi/ipds/package/actions
Response example:
{
"desc" : "Execute an action over the relianoid-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/actions
Apply action about the relianoid-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://<relianoid_server>:444/api/v4.0/api.cgi/ipds
zcli ipds list
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:
- Remotes: Lists are obtained from a URL, those lists are not modifiable and can be scheduled to be downloaded.
- 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 RELIANOID 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://<relianoid_server>:444/api/v4.0/api.cgi/ipds/blacklists
zcli ipds-blacklist list
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://<relianoid_server>:444/api/v4.0/api.cgi/ipds/blacklists/loc
zcli ipds-blacklist get 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://<relianoid_server>:444/api/v4.0/api.cgi/ipds/blacklists
ipds-blacklist create -name newListLoc -type local -policy allow
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://<relianoid_server>:444/api/v4.0/api.cgi/ipds/blacklists
POST /ipds/blacklists
Create a blacklist to be used in the farms. Blacklists can be of two types:
- Local: The sources are added by the user. The list is saved locally.
- Remote: The sources are obtained from a remote location. This location is indicated by a URL. The remote list format supported is one Network address/Mask bit or IP line per line.
Request parameters
Field | Type | Description | Required |
---|---|---|---|
name | String | Blacklist name. It is used as 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://<relianoid_server>:444/api/v4.0/api.cgi/ipds/blacklists/whiteList
zcli ipds-blacklist set whiteList -policy allow
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://<relianoid_server>:444/api/v4.0/api.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://<relianoid_server>:444/api/v4.0/api.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://<relianoid_server>:444/api/v4.0/api.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://<relianoid_server>:444/api/v4.0/api.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://<relianoid_server>:444/api/v4.0/api.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://<relianoid_server>:444/api/v4.0/api.cgi/ipds/blacklists/remoteList
zcli ipds-blacklist delete 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 GET -H "ZAPI_KEY: <ZAPI_KEY_STRING>"
https://<relianoid_server>:444/api/v4.0/api.cgi/ipds/blacklists/localList/sources
zcli ipds-blacklist get 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 sources 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://<relianoid_server>:444/api/v4.0/api.cgi/ipds/blacklists/localList/sources
zcli ipds-blacklist-source add localList -source 192.168.3.1
Request example for batching:
curl -k -X POST -H "ZAPI_KEY: <ZAPI_KEY_STRING>" -H 'Content-Type: application/json'
-d '{"source":["192.168.3.1", "22.2.32.7"]}'
https://<relianoid_server>:444/zapi/v4.1/zapi.cgi/ipds/blacklists/localList/sources
zcli ipds-blacklist-source add localList -source 192.168.3.1,22.2.32.7
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 or 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://<relianoid_server>:444/api/v4.0/api.cgi/ipds/blacklists/localList/sources/2
ipds-blacklist-source set localList 2 -source 192.168.3.1
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://<relianoid_server>:444/api/v4.0/api.cgi/ipds/blacklists/localList/sources/2
zcli ipds-blacklist-source remove localList 2
Request example for batching:
curl -k -X DELETE -H "ZAPI_KEY: <ZAPI_KEY_STRING>"
https://<relianoid_server>:444/zapi/v4.1/zapi.cgi/ipds/blacklists/localList/sources/65.21.7.2,90.53.0.11/24,5.82.2.64
zcli ipds-blacklist-source remove localList 65.21.7.2,90.53.0.11/24,5.82.2.64
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://<relianoid_server>:444/api/v4.0/api.cgi/ipds/blacklists/remoteList/actions
zcli ipds-blacklist update remoteList
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://<relianoid_server>:444/api/v4.0/api.cgi/ipds/dos/rules
zcli ipds-dos list
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://<relianoid_server>:444/api/v4.0/api.cgi/ipds/dos
zcli ipds-dos list
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://<relianoid_server>:444/api/v4.0/api.cgi/ipds/dos/limitConnHttp
zcli ipds-dos get limitConnHttp
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 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://<relianoid_server>:444/api/v4.0/api.cgi/ipds/dos
zcli ipds-dos create -name limitUsers -rule limitsec
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://<relianoid_server>:444/api/v4.0/api.cgi/ipds/dos/ssh_brute_force
zcli ipds-dos set ssh_brute_force -hits 10 -status up -time 100
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://<relianoid_server>:444/api/v4.0/api.cgi/ipds/dos/limitConnHttp
zcli ipds-dos delete 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://<relianoid_server>:444/api/v4.0/api.cgi/ipds/dos/conns_maximum/actions
zcli ipds-dos start conns_maximum
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://<relianoid_server>:444/api/v4.0/api.cgi/ipds/rbl
zcli ipds-rbl list
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.relianoid.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://<relianoid_server>:444/api/v4.0/api.cgi/ipds/rbl/protection_ssh
zcli ipds-rbl get 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.relianoid.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://<relianoid_server>:444/api/v4.0/api.cgi/ipds/rbl
zcli ipds-rbl create -name all
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://<relianoid_server>:444/api/v4.0/api.cgi/ipds/rbl/all
zcli ipds-rbl set all -name all_reported -cache_size 16384 -cache_time 180000 -queue_size 32269 -threadmax 500 -local_traffic true -log_level 4 -only_logging true
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://<relianoid_server>:444/api/v4.0/api.cgi/ipds/rbl/all_reported
zcli ipds-rbl create -name copied_rule -copy_from 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://<relianoid_server>:444/api/v4.0/api.cgi/ipds/rbl/sip
zcli ipds-rbl delete 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://<relianoid_server>:444/api/v4.0/api.cgi/ipds/rbl/domains
zcli ipds-rbl-domain list
GET /ipds/rbl/domains
List all available domains to link with RBL rules.
Response example:
{
"description" : "Get RBL domains",
"params" : {
"preloaded" : [
{
"domain" : "all.rbl.relianoid.com",
"id" : 0
},
{
"domain" : "ssh.rbl.relianoid.com",
"id" : 1
},
{
"domain" : "sip.rbl.relianoid.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 RELIANOID 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://<relianoid_server>:444/api/v4.0/api.cgi/ipds/rbl/domains
zcli ipds-rbl-domain add -domain web.dnsbl.sorbs.net
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://<relianoid_server>:444/api/v4.0/api.cgi/ipds/rbl/domains/2
zcli ipds-rbl-domain 2 -domain ssh.blocklist.de
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://<relianoid_server>:444/api/v4.0/api.cgi/ipds/rbl/domains/1
zcli ipds-rbl-domain remove 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.relianoid.com"}'
https://<relianoid_server>:444/api/v4.0/api.cgi/ipds/rbl/tstrule/domains
zcli ipds-rbl add tstrule -domain apache.rbl.relianoid.com
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.relianoid.com' to the RBL rule tstrule",
"message" : "Added apache.rbl.relianoid.com domain successfully.",
"params" : {
"cache_size" : 8192,
"cache_time" : 3600,
"domains" : [
{
"domain" : "apache.rbl.relianoid.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://<relianoid_server>:444/api/v4.0/api.cgi/ipds/rbl/tstrule/domains/apache.rbl.relianoid.com
zcli ipds-rbl-domain remove all -domain apache.rbl.relianoid.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.relianoid.com from a RBL rule tstrule",
"message" : "The domain apache.rbl.relianoid.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://<relianoid_server>:444/api/v4.0/api.cgi/ipds/rbl/<name>/action
zcli ipds-rbl stop <name>
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.
RELIANOID 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:
Executing the rule: resolution, matches, phase and execute.
Logging information: audit, log and log_data.
Adding information to the response: redirect_url.
Information about the rule: description, id, raw, rule_id, severity and tag.
Managing the flow of the checking rules: skip and skip_after.
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 relianoid-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://<relianoid_server>:444/api/v4.0/api.cgi/ipds/waf
zcli ipds-waf list
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://<relianoid_server>:444/api/v4.0/api.cgi/ipds/waf/test_waf_ori
zcli ipds-waf get 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://<relianoid_server>:444/api/v4.0/api.cgi/ipds/waf
zcli ipds-waf create -name CUSTOM-RULESET
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: |
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://<relianoid_server>:444/api/v4.0/api.cgi/ipds/waf/CUSTOM-RULESET
zcli ipds-waf set CUSTOM-RULESET -audit true -process_request_body true -request_body_limit 645656 -process_response_body true -only_logging false
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 that is configured in the parameter redirect_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. |
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. |
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://<relianoid_server>:444/api/v4.0/api.cgi/ipds/waf/test_waf_copied
zcli ipds-waf delete 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://<relianoid_server>:444/api/v4.0/api.cgi/ipds/waf/test_waf_ori/rules/0
zcli ipds-waf-rule get test_waf_ori 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://<relianoid_server>:444/api/v4.0/api.cgi/ipds/waf/CUSTOM-RULESET/rules
zcli ipds-waf-rule CUSTOM-RULESET -mark END-SET1
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,"description":"Testing rule","phase":2,"execute":"/opt/example_script.lua","log":"true",
"skip":2,"rule_id":199,"audit":"false"}'
https://<relianoid_server>:444/api/v4.0/api.cgi/ipds/waf/CUSTOM-RULESET/rules
zcli ipds-rule create CUSTOM-RULESET -skip_after
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. |
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. |
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 relianoid-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://<relianoid_server>:444/api/v4.0/api.cgi/ipds/waf/test_waf_ori/rules
zcli ipds-waf-rule create test_waf_ori -copy_from 12312
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://<relianoid_server>:444/api/v4.0/api.cgi/ipds/waf/test_waf_ori/rules
NOT IMPLEMENTED
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 shown 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://<relianoid_server>:444/api/v4.0/api.cgi/ipds/waf/test_waf_ori/rules/0
zcli ipds-waf-rule set test_waf_ori 0 -log false -resolution deny -description "Rule to modify the another one" -rule_id 200 -skip 1 -phase 4 -skip_after 12
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://<relianoid_server>:444/api/v4.0/api.cgi/ipds/waf/test_waf_ori/rules/0/actions
zcli ipds-waf-rule move test_waf_ori 0 -position 2
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://<relianoid_server>:444/api/v4.0/api.cgi/ipds/waf/test_waf_ori/rules/0
zcli ipds-waf-rule delete test_waf_ori 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://<relianoid_server>:444/api/v4.0/api.cgi/ipds/waf/test_waf_ori/rules/0/matches
zcli ipds-waf-rule-match create test_waf_ori 0 -not_match true -multi_match false -capture true -operating "" -operator detectSQLi
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://<relianoid_server>:444/api/v4.0/api.cgi/ipds/waf/test_waf_ori/rules/0/matches/0
zcli ipds-waf-rule-match set test_waf_ori 0 0 -capture false -multi_match true -not_match false
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://<relianoid_server>:444/api/v4.0/api.cgi/ipds/waf/test_waf_ori/rules/0/matches/0
zcli ipds-waf-rule-match delete test_waf_ori 0 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://<relianoid_server>:444/api/v4.0/api.cgi/farms/httpTest/ipds/waf/test_waf_copied/actions
zcli farm-waf move httpTest test_waf_copied -position 0
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://<relianoid_server>:444/api/v4.0/api.cgi/ipds/waf/test_waf_copied/actions
zcli ipds-waf start test_waf_copied
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. |
List the WAF Files
List the WAF Files
Request example:
curl -k -X GET -H "ZAPI_KEY: <ZAPI_KEY_STRING>"
https://<relianoid_server>:444/api/v4.0/api.cgi/ipds/waf/files
This call is available from version 4.0.1
NOT IMPLEMENTED
GET /ipds/waf/files
List the files available to use in a WAF rule
Response example:
{
"description" : "List the WAF files",
"params" : [
{
"module" : "blacklist",
"name" : "All",
"path" : "/usr/local/relianoid/config/ipds/blacklists/lists/All.txt",
"type" : "data"
},
{
"module" : "blacklist",
"name" : "apache_list",
"path" : "/usr/local/relianoid/config/ipds/blacklists/lists/apache_list.txt",
"type" : "data"
},
{
"module" : "waf",
"name" : "crawlers-user-agents",
"path" : "/usr/local/relianoid/config/ipds/waf/sets/crawlers-user-agents.data",
"type" : "data"
},
]
}
Response parameters
The response is a JSON with the list of available files and data about them. The parameters that appears in a file object are:
Field | Type | Description |
---|---|---|
module | String | It is the module where the file is. Files can be of waf or blacklist modules. |
name | String | It is the file name and it is used as unique identifier. |
path | String | It is the path file in the system. |
type | String | The files can be of: data type, if it contains data list; o script if the file a LUA script that can be used with the execute parameter of the WAF rules. |
Retrieve a WAF File
Retrieve a WAF File
Request example:
curl -k -X GET -H "ZAPI_KEY: <ZAPI_KEY_STRING>"
https://<relianoid_server>:444/api/v4.0/api.cgi/ipds/waf/files/Private_networks
NOT IMPLEMENTED
This call is available from version 4.0.1
GET /ipds/waf/files/<name>
Show the content of a file
The name URI parameter is the WAF File name that is used as unique identifier.
Response example:
{
"description" : "Get the WAF file Private_networks",
"params" : {
"content" : "0.0.0.0/8\n10.0.0.0/8\n100.64.0.0/10\n127.0.0.0/8\n169.254.0.0/16\n172.16.0.0/12\n192.0.0.0/24\n192.0.2.0/24\n192.88.99.0/24\n192.168.0.0/16\n198.18.0.0/15\n198.51.100.0/24\n203.0.113.0/24\n224.0.0.0/3\n",
"type" : "data"
}
}
Response parameters
The response is a JSON object with the key params that contains the following fields:
Field | Type | Description |
---|---|---|
content | String | It is a string with the content of the file. |
type | String | The files can be of: data type, if it contains data list; o script if the file a LUA script that can be used with the execute parameter of the WAF rules. |
Create or Modify a WAF File
Create or Modify a WAF File
Request example:
curl -k -X PUT -H "ZAPI_KEY: <ZAPI_KEY_STRING>" -H 'Content-Type: application/json'
-d '{"type":"data","content":"192.168.200.1\n192.168.200.2\n192.168.200.3"}'
https://<relianoid_server>:444/api/v4.0/api.cgi/ipds/waf/files/blocked_ips
NOT IMPLEMENTED
This call is available from version 4.0.1
PUT /ipds/waf/files/<name>
Create (or overwrite if already exists) a file that contains useful data to create WAF rules.
The name URI parameter is the WAF file name that will be used as unique identifier.
Request parameters
Field | Type | Description | Required |
---|---|---|---|
content | String | It is a string with the content of the file. | true |
type | String | The files can be of: data type, if it contains data list; o script if the file a LUA script that can be used with the execute parameter of the WAF rules. | true |
Response example:
{
"description" : "Create the WAF file 'blocked_ips'",
"message" : "The file 'blocked_ips' was created properly"
}
Delete a WAF File
Delete a WAF File
Request example:
curl -k -X DELETE -H "ZAPI_KEY: <ZAPI_KEY_STRING>"
https://<relianoid_server>:444/api/v4.0/api.cgi/ipds/waf/blocked_ips
NOT IMPLEMENTED
This call is available from version 4.0.1
DELETE /ipds/waf/<name>
Delete a WAF file.
The name URI parameter is the WAF File name that is used as unique identifier.
Response example:
{
"description" : "Delete the WAF file 'blocked_ips'",
"message" : "The WAF file 'blocked_ips' has been deleted successfully.",
"success" : "true"
}
System
System options offer you the possibility of personalizing the services that are 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://<relianoid_server>:444/api/v4.0/api.cgi/system/version
zcli system get
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",
"relianoid_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. |
relianoid_version | String | RELIANOID version. |
Show information
Show information
Request example:
curl -k -X GET -H "ZAPI_KEY: <ZAPI_KEY_STRING>"
https://<relianoid_server>:444/api/v4.0/api.cgi/system/info
zcli system get
This call is available from version 4.0.1
GET /system/info
Show extended information about the system.
Response example:
{
"description" : "Get the system information",
"params" : {
"appliance_version" : "ZVA 6000, hypervisor: Xen",
"certificate_key" : "###################",
"edition" : "enterprise",
"hostname" : "devcano-6000",
"kernel_version" : "4.19.37-z6000",
"language" : "",
"last_zapi_version" : "4.0.1",
"supported_zapi_versions" : [
"3",
"3.1",
"3.2",
"4.0.1"
],
"system_date" : "Tue Dec 3 11:39:44 2019",
"user" : "root",
"relianoid_version" : "_VERSION_"
}
}
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. |
certificate_key | String | System key used to activate the product. |
edition | String | It shows if the version is enterprise or community edition. |
hostname | String | Host name. |
kernel_version | String | Linux kernel version used by the system. |
language | String | Language set in the WEB GUI. |
last_zapi_version | String | The last zapi version that the current RELIANOID version supports. |
supported_zapi_versions | String [ ] | List of Zapi versions that the current RELIANOID version supports |
system_date | String | System date. |
user | String | Current user used for the session of for the Zapi request. |
relianoid_version | String | RELIANOID version. |
Modify Language
Modify Language
Request example:
curl -k -X POST -H 'Content-Type: application/json' -H "ZAPI_KEY: <ZAPI_KEY_STRING>"
-d '{"language":"english"}'
https://<relianoid_server>:444/api/v4.0/api.cgi/system/language
zcli system-language set -language english
POST /system/language
Modify the Language in the WEB GUI.
Request parameters
Field | Type | Description |
---|---|---|
language | String | Language used in the WEB GUI. |
Response example:
{
"description" : "Modify the WebGUI language",
"message" : "Success",
"params" : {
"language" : "english"
}
}
Response parameters
The response will be a JSON with all requested values updated. See the response example for more information.
Modify Language
Modify Language
Request example:
curl -k -X POST -H 'Content-Type: application/json' -H "ZAPI_KEY: <ZAPI_KEY_STRING>"
-d '{"language":"english"}'
https://<relianoid_server>:444/api/v4.0/api.cgi/system/language
zcli system-language set -language english
POST /system/language
Modify the Language in the WEB GUI.
Request parameters
Field | Type | Description |
---|---|---|
language | String | Language used in the WEB GUI. |
Response example:
{
"description" : "Modify the WebGUI language",
"message" : "Success",
"params" : {
"language" : "english"
}
}
Response parameters
The response will be a JSON with all requested values updated. See the response example for more information.
Show the IDs tree
Show the IDs tree
Request example:
curl -k -X GET -H "ZAPI_KEY: <ZAPI_KEY_STRING>"
https://<relianoid_server>:444/api/v4.0/api.cgi/ids
This call is available from version 4.0.1
GET /ids
It retrieves a tree with all of load balancer modules IDs objects.
Response example:
{
"description" : "Get a load balancer object IDs",
"params" : {
"aliases" : {
"backends" : {
"192.168.100.254" : null
},
"interfaces" : null
},
"certificates" : {
"asdf.csr" : null,
"zencert.pem" : null
},
"farmguardians" : {
"check_blackboard" : null,
"check_http" : null
},
"farms" : {
"farm1" : {
"ipds" : {
"blacklists" : null,
"dos" : null
},
"services" : {
"default_service" : {
"backends" : {
"0" : null
}
}
}
},
"newfarm" : {
"certificates" : null,
"ipds" : {
"blacklists" : null,
"dos" : null,
"waf" : null
},
"services" : {
"newservice" : {
"backends" : {
"0" : null
},
"fg" : {
"newfg" : null
}
}
}
},
"newfarm4" : {
"ipds" : {
"blacklists" : null,
"dos" : null
},
"services" : {
"default_service" : {
"backends" : {
"0" : null
},
"fg" : {
"newfg" : null
}
}
}
},
"newfarm6" : {
"ipds" : {
"blacklists" : null,
"dos" : null
},
"services" : {
"newservice" : {
"backends" : {
"1" : null
},
"fg" : {
"newfg" : null
}
}
},
"zones" : null
},
"newfarm7" : {
"ipds" : {
"blacklists" : null,
"dos" : null
},
"services" : {
"default_service" : {
"backends" : {
"0" : null
}
}
}
}
},
"interfaces" : {
"bonding" : null,
"nic" : {
"eth0" : null,
"eth1" : null
},
"virtual" : {
"eth1.1:vir" : null,
"eth1.2:23" : null
},
"vlan" : {
"eth1.1" : null,
"eth1.2" : null
}
},
"ipds" : {
"blacklists" : {
"All" : null,
"Private_networks" : null,
"relianoid_mail_spammer_list" : null
},
"dos" : null,
"rbl" : {
"dsfs" : null
},
"waf" : {
"REQUEST-90-CONFIGURATION" : null,
"REQUEST-901-INITIALIZATION" : null
}
},
"rbac" : {
"groups" : null,
"roles" : {
"management" : null,
"monitoring" : null
},
"users" : null
},
"routing" : {
"tables" : {
"main" : null,
"table_eth0" : null,
"table_eth1" : null,
"table_eth1.1" : null,
"table_eth1.2" : null
}
},
"system" : {
"backup" : {
"backup-config" : null
},
"logs" : {
"syslog" : null,
"syslog.1.gz" : null
}
}
}
}
Response parameters
The response will be a JSON object with the struct that is displayed in the example. Each item is a key that represets a load balancer module or an object. The end of a tree branch is indicated with the value null.
Show DNS
Show DNS
Request example:
curl -k -X GET -H "ZAPI_KEY: <ZAPI_KEY_STRING>"
https://<relianoid_server>:444/api/v4.0/api.cgi/system/dns
zcli system-services-dns get
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://<relianoid_server>:444/api/v4.0/api.cgi/system/dns
zcli system-services-dns set -secondary 8.8.8.8 -primary 8.8.4.4
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://<relianoid_server>:444/api/v4.0/api.cgi/system/snmp
system-services-snmp get
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://<relianoid_server>:444/api/v4.0/api.cgi/system/snmp
system-services-snmp set -ip 192.168.100.241 -port 170 -scope 0.0.0.0/0 -status true -community public
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://<relianoid_server>:444/api/v4.0/api.cgi/system/license/txt
GET /system/license/<format>
Show the RELIANOID 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://<relianoid_server>:444/api/v4.0/api.cgi/system/ntp
zcli system-services-ntp get
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://<relianoid_server>:444/api/v4.0/api.cgi/system/ntp
system-services-ntp set -server pool.ntp.org
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://<relianoid_server>:444/api/v4.0/api.cgi/system/ssh
zcli system-services-ssh get
GET /system/ssh
Show the SSH service configuration. Multiple ips and ports can be configured from version 4.0.2.
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. From version 4.0.2, multiple ips can be returned in an array. |
port | String | Port configurated for SSH service. From version 4.0.2, multiple ports can be returned in an array. |
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://<relianoid_server>:444/api/v4.0/api.cgi/system/ssh
Request example for batching:
curl -k -X POST -H 'Content-Type: application/json' -H "ZAPI_KEY: <ZAPI_KEY_STRING>"
-d '{"listen":["192.168.100.241","192.168.101.241"],"port":["22","23"]}'
https://<relianoid_server>:444/api/v4.0/api.cgi/system/ssh
zcli system-services-ssh set -listen 192.168.100.241 -port 22
POST /system/ssh
Modify the SSH service configuration. Multiple ips and ports can be configured from version 4.0.2.
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. Enabled to set an array to configure multiple ips from version 4.0.2. |
port | String | Port configurated for SSH service. Enabled to set an array to configure multiple ports from version 4.0.2. |
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://<relianoid_server>:444/api/v4.0/api.cgi/system/http
zcli system-services-http get
GET /system/http
Show the HTTP service configuration. It is where RELIANOID API and GUI are running. Multiple ips and ports can be configured from version 4.0.2.
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. From version 4.0.2, multiple ips can be returned in an array. |
port | String | Port where HTTP service is listening. From version 4.0.2, multiple ports can be returned in an array. |
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":"443","force":"true"}'
https://<relianoid_server>:444/api/v4.0/api.cgi/system/http
Request example for batching:
curl -k -X POST -H "ZAPI_KEY: <ZAPI_KEY_STRING>" -H 'Content-Type: application/json'
-d '{"ip":["192.168.100.241", "192.168.101.241"],"port":["443", "444"],"force":"true"}'
https://<relianoid_server>:444/zapi/v4.1/zapi.cgi/system/http
zcli system-services-http set -ip 192.168.100.241 -port 443
POST /system/http
Modify the HTTP service configuration. Multiple ips and ports can be configured from version 4.0.2.
Request parameters
Field | Type | Description |
---|---|---|
ip | String | is the IP where the HTTPS service is listening. The character * is used to listen in all configurated IPs. Enabled to set an array to configure multipe ips from version 4.0.2. |
port | String | Port where HTTPS service is listening. Enabled to set an array to configure multiple ports from version 4.0.2. |
force | String | "true" or "false". Necessary to be able to apply the changes, as this change may affect the accessibility to the system. If this parameter is missing or its value is "false", the API reponses with 400 code value and the message: "The web server will be restarted and won't be accessible from its current IP anymore. The load balancer GUI will be accesible from IP:PORT when the restart is over. If you agree, execute again sending the parameter 'force'" |
Response example:
{
"description" : "Post http",
"params" : {
"ip" : "192.168.100.241",
"port" : "443"
}
}
Response example when not including the force parameter:
{
"description" : "Post http",
"documentation" : "https://www.relianoid.com/zapidocv4.0",
"error" : "true",
"message" : "The web server will be restarted and won't be accessible from its current IP anymore. The load balancer GUI will be accesible from 192.168.100.241:443 when the restart is over. If you agree, execute again sending the parameter 'force'"
}
Response parameters
The response will be a JSON with all requested values updated. See the response example for more information.
Modify HTTPS server certificate
Modify HTTPS server certificate
Request example:
curl -k -X POST -H 'Content-Type: application/json' -H "ZAPI_KEY: <ZAPI_KEY_STRING>"
-d '{"certificate":"zencert.pem"}'
https://<relianoid_server>:444/api/v4.0/api.cgi/system/https/certificate
zcli system-service-https-certificate set -certificate zencert.pem
POST /system/https/certificate
Modify the HTTPS service certificate.
Request parameters
Field | Type | Description |
---|---|---|
certificate | String | Certificate name. |
Response example:
{
"description" : "Add certificate to RELIANOID HTTPS server",
"message" : "The certificate zencert.pem has been added to the HTTPS Server succesfully",
"success" : "true"
}
Response parameters
The response will be a JSON with all requested values updated. See the response example for more information.
Show Proxy
Show Proxy
Request example:
curl -k -X GET -H "ZAPI_KEY: <ZAPI_KEY_STRING>"
https://<relianoid_server>:444/api/v4.0/api.cgi/system/proxy
zcli system-services-proxy get
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://<relianoid_server>:444/api/v4.0/api.cgi/system/proxy
zcli system-services-proxy set -http_proxy http://10.10.10.12:888 -https_proxy https://10.10.10.12:8888
POST /system/proxy
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.
Show Global Settings
Show Global Settings
Request example:
curl -k -X GET -H "ZAPI_KEY: <ZAPI_KEY_STRING>"
https://<relianoid_server>:444/api/v4.0/api.cgi/system/global
zcli system-global get
GET /system/global
Show the status of some global settings
Response example:
{
"description" : "Get the RELIANOID global settings",
"params" : {
"arp_announce" : "false",
"duplicated_network" : "false",
"ssyncd" : "true",
"proxy_new_generation" : "true",
"waf_assistant" : "false"
}
}
Response parameters
The response will be a JSON object with the below parameters.
Field | Type | Description |
---|---|---|
arp_announce | String | If this parameter is enabled true, the master node of the cluster will send a ARP packet to the network per minute and when the system boots. If the value is false the packet will be sent only when cluster switches to master or when a interface will be configurated. |
duplicated_network | String | If this parameter is enabled true, the system will able to manage networks duplicated in different interfaces, a process will ensure that an interface does not route through another with the same netwoking. This can be disabled with the value false. |
ssyncd | String | Session synchronization daemon is which replies the client sessions between master and backup nodes for a cluster. This feature is enabled with the value true and disabled with false. |
proxy_new_generation | String | It sets the HTTP load balancer core. If it has the value true, the new core zproxy will be used, it is more efficient (It is available since RELIANOID 6.1). The value false will use the old HTTP load balancer core. Modifying this value will restart the HTTP farms. |
waf_assistant | String | From version 4.0.2. If this parameter is enabled true, the system will assist the user with WAF settings of the farms. |
Modify Global
Modify Global
Request example:
curl -k -X POST -H 'Content-Type: application/json' -H "ZAPI_KEY: <ZAPI_KEY_STRING>"
-d '{"arp_announce":"false","duplicated_network":"true","ssyncd":"true"}'
https://<relianoid_server>:444/api/v4.0/api.cgi/system/global
This call is available from version 4.0.1
POST /system/global
Modify the RELIANOID global Settings
Request parameters
Field | Type | Description |
---|---|---|
arp_announce | String | If this parameter is enabled true, the master node of the cluster will send a ARP packet to the network per minute and when the system boots. If the value is false the packet will be sent only when cluster switches to master or when a interface will be configurated. |
duplicated_network | String | If this parameter is enabled true, the system will able to manage networks duplicated in different interfaces, a process will ensure that an interface does not route through another with the same netwoking. This can be disabled with the value false. |
ssyncd | String | Session synchronization daemon is which replies the client sessions between master and backup nodes for a cluster. This feature is enabled with the value true and disabled with false. |
proxy_new_generation | String | It sets the HTTP load balancer core. If it has the value true, the new core zproxy will be used, it is more efficient (It is available since RELIANOID 6.1). The value false will use the old HTTP load balancer core. Modifying this value will restart the HTTP farms. |
waf_assistant | String | From version 4.0.2. If this parameter is enabled true, the system will assist the user with WAF settings of the farms. |
force | String | This parameter is used to force the settings when these require a service restart. This parameter accepts the value true. |
Response example:
{
"description" : "Set the RELIANOID global settings",
"params" : {
"arp_announce" : "false",
"duplicated_network" : "true",
"ssyncd" : "true",
"proxy_new_generation" : "true",
"waf_assistant" : "false"
}
}
Response parameters
The response will be a JSON with all requested values updated. See the response example for more information.
Show rsyslog server
Show rsyslog conf
Request example:
curl -k -X GET -H "ZAPI_KEY: <ZAPI_KEY_STRING>"
https://<relianoid_server>:444/api/v4.0/api.cgi/system/rsyslog
zcli system-rsyslog get
GET /system/rsyslog
This call is available from version 4.0.2
Show the rsyslog service configuration. It is possible to configure rsyslog service for forwarding log messages in an IP network.
Response example:
{
"description" : "Get rsyslog configuration",
"params" : {
"ip" : "192.168.10.199",
"port" : "514",
"protocol" : "tcp"
}
}
Response parameters
The response will be a JSON object with the below parameters.
Field | Type | Description |
---|---|---|
ip | String | Remote Ip where log server is listening. |
port | String | Remote Port where log server is listening. |
protocol | String | Protocol Type. The options are: tcp or udp. |
Modify rsyslog server
Modify rsyslog conf
Request example:
curl -k -X POST -H 'Content-Type: application/json' -H "ZAPI_KEY: <ZAPI_KEY_STRING>"
-d '{"ip":"192.168.10.199","port":"514","protocol":"tcp"}'
https://<relianoid_server>:444/api/v4.0/api.cgi/system/rsyslog
zcli system-rsyslog set -ip 192.168.10.199 -port 514
POST /system/rsyslog
This call is available from version 4.0.2
Modify the rsyslog service configuration.
Request parameters
Field | Type | Description | Required |
---|---|---|---|
ip | String | Remote Ip where log server is listening. | True |
port | Number | Remote Port where log server is listening. If no port is specified, the default value will be 514. | False |
protocol | String | Protocol Type. The options are: tcp(for the TCP protocol) or udp(for the UDP protocol). If none is specified, the default protocol used will be UDP. | False |
Response example:
{
"description" : "Set rsyslog configuration",
"params" : {
"ip" : "192.168.10.199",
"port" : "514",
"protocol" : "tcp"
}
}
Response parameters
The response will be a JSON with all requested values updated. See the response example for more information.
Delete rsyslog configuration
Delete rsyslog conf
Request example:
curl -k -X DELETE -H "ZAPI_KEY: <ZAPI_KEY_STRING>"
https://<relianoid_server>:444/api/v4.0/api.cgi/system/rsyslog
zcli system-rsyslog unset
Response example:
{
"description" : "Unset rsyslog configuration",
"message" : "Rsyslog configuration unset successfully"
}
DELETE /system/rsyslog
This call is available from version 4.0.2
Unset the rsyslog service configuration.
Retrieve the current user
Retrieve the current user
Request example:
curl -k -X GET -H "ZAPI_KEY: <ZAPI_KEY_STRING>"
https://<relianoid_server>:444/api/v4.0/api.cgi/system/users
zcli system-user get
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 RELIANOID 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://<relianoid_server>:444/api/v4.0/api.cgi/system/users
zcli system-user set -password CDe0c3ck -newpassword v2mfcvv2 -zapi_permissions false -zapikey vCeH60mQFf2MgH5
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://<relianoid_server>:444/api/v4.0/api.cgi/system/logs
zcli system-log list
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://<relianoid_server>:444/api/v4.0/api.cgi/system/logs/kern.log/lines/2
zcli system-log get kern.log 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://<relianoid_server>:444/api/v4.0/api.cgi/system/logs/syslog.2.gz > log.gz
zcli system-log download syslog.2.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://<relianoid_server>:444/api/v4.0/api.cgi/system/backup
zcli system-backup list
GET /system/backup
Response example:
{
"description" : "Get backups",
"params" : [
{
"date" : "2019-12-16 16:44:00 UTC",
"name" : "backup1",
"version" : "5.2.17"
},
{
"version" : "5.2.17",
"date" : "2019-12-16 15:41:42 UTC",
"name" : "fresh"
}
]
}
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 . |
+ in EE version:
Field | Type | Description |
---|---|---|
version | String | It is the RELIANOID version that the system had when backup was created. |
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://<relianoid_server>:444/api/v4.0/api.cgi/system/backup
zcli system-backup create -name firstConf
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://<relianoid_server>:444/api/v4.0/api.cgi/system/backup/firstConf > ~/relianoidConf.tar.gz
zcli system-backup download firstConf
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://<relianoid_server>:444/api/v4.0/api.cgi/system/backup/newbackup
zcli system-backup upload newbackup /opt/1mar.tar.gz
PUT /system/backup/<name>
Upload a locally stored backup to RELIANOID. name is the backup unique identifier which will be stored in RELIANOID.
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://<relianoid_server>:444/api/v4.0/api.cgi/system/backup/firstConf
zcli system-backup delete firstConf
DELETE /system/backup/<name>
Delete a backup file from the RELIANOID 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://<relianoid_server>:444/api/v4.0/api.cgi/system/backup/firstConf/actions
zcli system-backup apply firstConf
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. |
force | String | Optional parameter, it must be used to force the backup applying if the backup version is different to the RELIANOID version.; |
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://<relianoid_server>:444/api/v4.0/api.cgi/system/supportsave > supportsave.tar.gz
zcli system-supportsave download 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://<relianoid_server>:444/api/v4.0/api.cgi/system/packages
zcli system-update list
GET /system/packages
List the updates available. The response contains the command line to update the packages.
Response example:
{
"description" : "RELIANOID 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",
"relianoid-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://<relianoid_server>:444/api/v4.0/api.cgi/system/factory
zcli system-factory apply -force true -interface eth0
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 backenk or cluster status (New monitoring options such as licensing, packages, certificates and interfaces have been added from version 6.2).
In the method section, you will be able to choose which sender will be used when RELIANOID has to send a notification.
Show alert status
Show alert status
Request example:
curl -k -X GET -H "ZAPI_KEY: <ZAPI_KEY_STRING>"
https://<relianoid_server>:444/api/v4.0/api.cgi/system/notifications/alerts
zcli system-notifications-alert-cluster get
zcli system-notifications-alert-backend get
zcli system-notifications-alert-interface get
zcli system-notifications-alert-certificate get
zcli system-notifications-alert-license get
zcli system-notifications-alert-package get
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"
},
{
"alert" : "certificate",
"status" : "disabled"
},
{
"alert" : "license",
"status" : "disabled"
},
{
"alert" : "package",
"status" : "disabled"
},
{
"alert" : "interface",
"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; cluster, send a notification when the cluster master node switches to another node. From version 6.2: certiticate, notifies when a used certificate is 7 days away from expiry; license, notifies when the licence is 30, 7 and 0 days away from expiry ; package, notifies when there are new packages availables; interface, notifies when one of the indicated interfaces changes state. |
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://<relianoid_server>:444/api/v4.0/api.cgi/system/notifications/alerts/backends
zcli system-notifications-alert-backend
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 for cluster
Field | Type | Description |
---|---|---|
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. |
Response parameters for backend
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. |
Response parameters for interface (From version 6.2)
Field | Type | Description |
---|---|---|
interfaces | It is an array of the names of the interfaces to be monitored. | |
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>"
-d '{"avoidflappingtime":10,"prefix":"[backend alert]"}'
https://<relianoid_server>:444/api/v4.0/api.cgi/system/notifications/alerts/backends
zcli system-notifications-alert-backend set -avoidflappingtime 10 -prefix "[backend alert]"
POST /system/notifications/alerts/<alert>
alert is the alert unique identifier.
Response parameters for cluster
Field | Type | Description |
---|---|---|
prefix | String | It is a prefix for the email subject, that are sent by the system for this kind of alert. |
Response parameters for backend
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. |
Response parameters for interface (From version 6.2)
Field | Type | Description |
---|---|---|
interfaces | String[ ] | It is an array of the names of the interfaces to be monitored. |
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://<relianoid_server>:444/api/v4.0/api.cgi/system/notifications/alerts/backends/actions
zcli system-notifications-alert-backend start
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://<relianoid_server>:444/api/v4.0/api.cgi/system/notifications/methods/email
zcli system-notifications-method-email get
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@relianoid.com",
"method" : "email",
"password" : "******",
"server" : "smtp.gmail.com",
"tls" : "true",
"to" : "adminuser@relianoid.net",
"user" : "user@relianoid.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@relianoid.com","password":"verystrongpass","server":"smtp.gmail.com","to":"adminuser@relianoid.net","tls":"true","user":"user@relianoid.com"}'
https://<relianoid_server>:444/api/v4.0/api.cgi/system/notifications/methods/email
zcli system-notifications-method-email set -from user@relianoid.com -password verystrongpass -server smtp.gmail.com -to adminuser@relianoid.com -tls true -user user@relianoid.com
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@relianoid.com",
"method" : "email",
"password" : "verystrongpass",
"server" : "smtp.gmail.com",
"tls" : "true",
"to" : "adminuser@relianoid.net",
"user" : "user@relianoid.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://<relianoid_server>:444/api/v4.0/api.cgi/system/notifications/methods/email/actions
zcli system-notifications-method-email test -from user@relianoid.com -password verystrongpass -server smtp.gmail.com -to adminuser@relianoid.com -tls true -user user@relianoid.com
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 - Server Certificate
RELIANOID allows to modify its load balancer server certificate (cherokee server). It is possible to assign any certificate that has been previously upladed. Take a look at the SSL Certificates section to see how to manage certificates
Get Server Certificate
Get the load balancer server certificate
Request example:
curl -k -X GET -H "ZAPI_KEY: <ZAPI_KEY_STRING>"
https://<relianoid_server>:444/api/v4.0/api.cgi/system/https/certificate
zcli system-https-certificate get
GET /system/https/certificate
This call is available from version 4.0.2
Show the HTTPS service certificate configured. It is the certificate used by the RELIANOID GUI. Obtain the certificate used by the load balancer server.
Response example:
The response will be a JSON object with the param "certificate". The value of this will be the certificate's name.
{
"description" : "Get https certificate",
"params" : {
"certificate" : "certificate.pem"
}
}
Response parameters
Field | Type | Description |
---|---|---|
certificate | String | Certificate name. |
Modify the load balancer server certificate
Modify the lb server certificate
Request example:
curl -k -X POST -H "ZAPI_KEY: <ZAPI_KEY_STRING>"
https://<relianoid_server>:444/api/v4.0/api.cgi/system/https/certificate
zcli system-https-certificate set -certificate certificate.pem
POST /system/https/certificate
Change the load balancer server certificate. The certificate must be previously uploaded.
Response example:
{
"description" : "Add certificate to RELIANOID HTTPS server",
"message" : "The certificate certificate.pem has been added to the HTTPS Server succesfully",
"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 RELIANOID, 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://<relianoid_server>:444/api/v4.0/api.cgi/system/cluster
zcli system-cluster get
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"
}
],
"track_interface" : []
}
}
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. |
track_interface | String[] | Interfaces to monitor. It is posible to monitor bond, nic or vlan interfaces. When a monitored interface goes down, the owning node switches to the maintenance state. (From version 4.0.2) |
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://<relianoid_server>:444/api/v4.0/api.cgi/system/cluster
zcli system-cluster create -local_ip 192.168.100.241 -remote_ip 192.168.100.240 -remote_password admin
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://<relianoid_server>:444/api/v4.0/api.cgi/system/cluster
zcli system-cluster set -check_interval 4 -failback disabled
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. |
track_interface | String[] | Interfaces to monitor. It is posible to monitor bond, nic or vlan interfaces. When a monitored interface goes down, the owning node switches to the maintenance state. Keep in mind that It is not posible to modify a monitored interface (From version 4.0.2). |
Response BODY:
{
"description" : "Modifying the cluster configuration",
"params" : {
"check_interval" : "4",
"failback" : "disabled",
"track_interface" : []
}
}
Disable the cluster
Disable the cluster
Request example:
curl -k -X DELETE -H 'Content-Type: application/json' -H "ZAPI_KEY: <ZAPI_KEY_STRING>"
https://<relianoid_server>:444/api/v4.0/api.cgi/system/cluster
zcli system-cluster delete
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://<relianoid_server>:444/api/v4.0/api.cgi/system/cluster/actions
zcli system-cluster maintenance
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://<relianoid_server>:444/api/v4.0/api.cgi/system/cluster/nodes
zcli system-cluster-node get
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://<relianoid_server>:444/api/v4.0/api.cgi/system/cluster/nodes/localhost
zcli system-cluster-localhost get
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. |
System - AWS
RELIANOID Load Balancer is able to be deployed on Amazon Web Services EC2 infrastructure. Check out the published article "Advanced Load Balancing and Clustering in Amazon Web Services" (https://www.relianoid.com/knowledge-base/howtos/advanced-load-balancing-and-clustering-in-amazon-web-services/) for more information.
Show the AWS user credentials configuration
Show the AWS user credentials configuration
Request example:
curl -k -X GET -H "ZAPI_KEY: <ZAPI_KEY_STRING>"
https://<relianoid_server>:444/api/v4.0/api.cgi/aws/credentials
zcli aws-credentials get
GET /aws/credentials
Show all configuration about the AWS configured credentials.
Response BODY:
{
"description" : "Retrieve the AWS credentials",
"params" : {
"access_key" : "EXAMPLEACCESSKEY",
"region" : "us-east-1",
"secret_key" : "********************",
"status" : ""
}
}
Response parameters
The response will be a JSON object with the AWS credentials info.
IAM user Object:
Field | Type | Description |
---|---|---|
access_key | String | Access key of IAM user. |
region | String | IAM User hosted location. |
secret_key | String | Secret key of IAM user. |
status | String | Credentials status message. The message will be empty if no credentials are configured or if they are configured but ok. If there is any problem with credentials, the message will be "Check your AWS Secret Access Key". |
Set the AWS user credentials
Set the AWS user credentials
Request example:
curl -k -X POST -H 'Content-Type: application/json' -H "ZAPI_KEY: <ZAPI_KEY_STRING>"
-d '{"access_key":"EXAMPLEACCESSKEY","secret_key":"EXAMPLESECRETKEY","region":"us-east-1"}'
https://<relianoid_server>:444/api/v4.0/api.cgi/aws/credentials
zcli aws-credentials set -access_key EXAMPLEACCESSKEY -secret_key EXAMPLESECRETKEY -region us-east-1
POST /aws/credentials
Set IAM user credentials.
Request parameters
Field | Type | Description |
---|---|---|
access_key | String | Access key of IAM user. |
region | String | IAM User hosted location. |
secret_key | String | Secret key of IAM user. |
Response BODY:
{
"description" : "Modify the AWS credentials",
"params" : {
"access_key" : "EXAMPLEACCESSKEY",
"region" : "us-east-1",
"secret_key" : "EXAMPLESECRETKEY"
}
}
System - Azure
RELIANOID Load Balancer is able to be deployed on Azure infrastructure. Check out the published article "Advanced Load Balancing and Clustering in Azure" (https://www.serverless.com/framework/docs/providers/aws/guide/credentials/) for more information.
Show the Azure AD user credentials
Show the Azure AD user credentials configuration
Request example:
curl -k -X GET -H "ZAPI_KEY: <ZAPI_KEY_STRING>"
https://<relianoid_server>:444/api/v4.0/api.cgi/azure/credentials
zcli azure-credentials get
GET /azure/credentials
Show configuration about the Azure configured credentials. Please note that RELIANOID does not store user credentials. Instead, it will use the credentials to create an active directory user.
Response BODY:
{
"description" : "Retrieve the Azure credentials",
"params" : {
"id" : "1cf4f8eb-9d9e-4966-b1fb-d41d5ff63ffd",
"name" : "http://az-zlb1_service_principal"
}
}
Response parameters
The response will be a JSON object with the AWS credentials info.
IAM user Object:
Field | Type | Description |
---|---|---|
id | String | Id of the active directory user. |
name | String | Name of the active directory user. |
Set the Azure AD user credentials
Set the Azure AD user credentials
Request example:
curl -k -X POST -H 'Content-Type: application/json' -H "ZAPI_KEY: <ZAPI_KEY_STRING>"
-d '{"access_key":"EXAMPLEACCESSKEY","secret_key":"EXAMPLESECRETKEY","region":"us-east-1"}'
https://<relianoid_server>:444/api/v4.0/api.cgi/azure/credentials
zcli azure-credentials set -user USER -password PASSWORD
POST /azure/credentials
Set azure user credentials. Please note that RELIANOID does not store user credentials. Instead, it will use the credentials to create an active directory user with only network permissions.
Request parameters
Field | Type | Description |
---|---|---|
user | String | Azure account user. |
password | String | Azure account password. |
Response BODY:
{
"description" : "Modify the Azure credentials",
"params" : {
"id" : "1cf4f8eb-9d9e-4966-b1fb-d41d5ff63ffd",
"name" : "http://az-zlb1_service_principal"
}
}
RBAC
RBAC is the solution for a Role Based Access Control. So, RELIANOID 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://<relianoid_server>:444/api/v4.0/api.cgi/rbac/users
zcli rbac-user list
GET /rbac/users
List all the RBAC users and their configurations
Response example:
{
"description" : "List the RBAC users",
"params" : [
{
"group" : "monitor",
"name" : "sarah",
"service" : "ldap",
"webgui_permissions" : "true",
"zapi_permissions" : "true"
},
{
"group" : "system-admin",
"name" : "john",
"service" : "local",
"webgui_permissions" : "true",
"zapi_permissions" : "true"
},
{
"group" : "web-admin",
"name" : "aaron",
"service" : "local",
"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. |
service | String | It is the service which valide the user. The options are: local, is the defult value and the user is created and managed in the load balancer; ldap, the user is validated using the rbac ldap configuration. |
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://<relianoid_server>:444/api/v4.0/api.cgi/rbac/users/sarah
zcli rbac-user get 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",
"service" : "local",
"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. |
service | String | It is the service which valide the user. The options are: local, is the defult value and the user is created and managed in the load balancer; ldap, the user is validated using the rbac ldap configuration. |
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","service":"local","password":"aCX2kl5m9"}'
https://<relianoid_server>:444/api/v4.0/api.cgi/rbac/users
zcli rbac-user create -name monica -service local -password aCX2kl5m9
POST /rbac/users
Create a user, the user is created without role and group.
Request parameters
Field | Type | Description | Required |
---|---|---|---|
name | String | User name, it identifies to the user and it used to access through the WebGUI. | true |
password | String | It is the password used by the user to access through the WebGUI. | true |
service | String | It is the service which valide the user. The options are: local, is the defult value and the user is created and managed in the load balancer; ldap, the user is validated using the rbac ldap configuration. |
{
"description" : "Create the RBAC user, monica",
"message" : "Added the RBAC user monica",
"params" : {
"user" : {
"group" : "",
"name" : "monica",
"service" : "local",
"webgui_permissions" : "false",
"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 object with the key users with 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. |
service | String | It is the service which valide the user. The options are: local, is the defult value and the user is created and managed in the load balancer; ldap, the user is validated using the rbac ldap configuration. |
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. |
Modify a user
Modify a user
Request example:
curl -k -X PUT -H 'Content-Type: application/json' -H "ZAPI_KEY: <ZAPI_KEY_STRING>"
-d '{ "zapi_permissions":"true","webgui_permissions":"true","newpassword":"8fhM42W1","zapikey":"m3dW2MyYt4Hgv3"}'
https://<relianoid_server>:444/api/v4.0/api.cgi/rbac/users/monica
zcli rbac-user set monica -zapi_permissions true -webgui_permissions true -newpassword 8fhM42W1 -zapikey m3dW2MyYt4Hgv3
PUT /rbac/users/<name>
Modify the configuration of a user. name is the user name and it is a unique identifier.
Request parameters:
Field | Type | Description | Required |
---|---|---|---|
zapikey | String | It is the group name where the user is. The user can be only in one group. | |
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. | |
newpassword | String | New user password to access through the WebGUI. |
Response example:
{
"description" : "Modify the RBAC user monica",
"message" : "Settings were changed successful.",
"params" : {
"group" : "",
"name" : "monica",
"service" : "ldap",
"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 a user object with 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. |
service | String | It is the service which valide the user. The options are: local, is the defult value and the user is created and managed in the load balancer; ldap, the user is validated using the rbac ldap configuration. |
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 |
Delete a user
Delete a user
Request example:
curl -k -X DELETE -H "ZAPI_KEY: <ZAPI_KEY_STRING>"
https://<relianoid_server>:444/api/v4.0/api.cgi/rbac/users/john
zcli rbac-user delete john
DELETE /rbac/users/<name>
Delete an RBAC user. name is the user name and it is a unique identifier.
Response example:
{
"description" : "Delete the RBAC user john",
"message" : "The RBAC user john has been deleted successful.",
"success" : "true"
}
RBAC - Roles
Role struct
Role example, these are all possible combination of objects and actions:
{
"message" : "Added the RBAC role newrole",
"params" : {
"role" : {
"rbac-user" : {
"show" : "false",
"delete" : "false",
"create" : "false",
"modify" : "false",
"list" : "false",
"menu" : "false"
},
"notification" : {
"show" : "false",
"modify" : "false",
"action" : "false",
"menu" : "false",
"test" : "false"
},
"rbac-role" : {
"modify" : "false",
"menu" : "false",
"delete" : "false",
"create" : "false",
"show" : "false"
},
"system-service" : {
"modify" : "false",
"menu" : "false"
},
"supportsave" : {
"download" : "false",
"menu" : "false"
},
"interface-virtual" : {
"modify" : "false",
"action" : "false",
"delete" : "false",
"create" : "false"
},
"farm" : {
"modify" : "false",
"menu" : "false",
"action" : "false",
"delete" : "false",
"create" : "false",
"maintenance" : "false"
},
"ipds" : {
"menu" : "false",
"modify" : "false",
"action" : "false"
},
"log" : {
"show" : "false",
"download" : "false",
"menu" : "false"
},
"alias" : {
"list" : "false",
"modify" : "false",
"menu" : "false",
"delete" : "false"
},
"rbac-group" : {
"show" : "false",
"menu" : "false",
"modify" : "false",
"list" : "false",
"delete" : "false",
"create" : "false"
},
"interface" : {
"modify" : "false",
"menu" : "false"
},
"certificate" : {
"menu" : "false",
"download" : "false",
"upload" : "false",
"create" : "false",
"delete" : "false",
"show" : "false"
},
"farmguardian" : {
"menu" : "false",
"modify" : "false"
},
"backup" : {
"menu" : "false",
"download" : "false",
"upload" : "false",
"delete" : "false",
"create" : "false",
"apply" : "false"
},
"cluster" : {
"maintenance" : "false",
"delete" : "false",
"create" : "false",
"menu" : "false",
"modify" : "false"
}
}
},
"description" : "Create the RBAC role, newrole"
}
A role defines a set of permissions that are applied to a group. All users of the group inherit the group role. A role is a set of objects, each object has actions. An action can have the value: "true", to allow the action or "false" to block the action.
Each object has available the shown actions in the role example. For example, for a farm, the available actions are "action", "create", "delete", "maintenance" and "modify"; or for an alias object, they are: "delete", "list" and "modify".
The objects
Field | Description |
---|---|
alias | It defines actions to manage the alias feature. |
backup | It defines actions to manage the backups. |
certificate | It defines actions to manage the SSL certificates. |
cluster | It defines actions to manage the cluster. |
farm | It defines actions to administrate the farms. The user only will be able to manage the farms of the user's group. |
farmguardian | It defines actions to manage farm health checks. To apply a farmguardian to a farm, the required object is farm. |
interface | It defines actions to administrate the network menu. The virtual interfaces are an exception, they are managed by the virtual-interfaces object. |
interface-virtual | It defines actions to administrate virtual interfaces. The user only will be able to manage the interfaces of the user's group. |
ipds | It defines actions to manage the IPDS rules. To apply a rule to a farm, the required object is farm. |
log | It defines actions to manage the load balancer logs. |
notification | It defines actions to manage notifications: alerts and sent methods. |
rbac-group | It defines actions to manage RBAC groups. |
rbac-role | It defines actions to manage RBAC roles. |
rbac-user | It defines actions to manage RBAC users. |
supportsave | It defines actions to manage the RELIANOID supportsave. |
system-service | It defines actions to manage remote and local services. |
The actions
Field | Description |
---|---|
list | It lists the available elements of an object. |
show | It retrieves an object and its configuration. |
download | It downloads an object from the load balancer. |
upload | It uploads an object to the load balancer. |
maintenance | It modifies the status of an object between maintenance and up. |
action | It applies an action to the object. Each object has its actions. |
create | It creates a new element for a type of object. |
delete | It deletes permanently an object. |
modify | It modifies the configuration of an object. Sometimes, if the object has not the actions: create, delete or action actions, these actions are applied by modify permission. |
List the roles
List all the roles
Request example:
curl -k -X GET -H "ZAPI_KEY: <ZAPI_KEY_STRING>"
https://<relianoid_server>:444/api/v4.0/api.cgi/rbac/roles
zcli rbac-role list
GET /rbac/roles
List all the RBAC roles
Response example:
{
"description" : "List the RBAC roles",
"params" : [
"example",
"admin",
"monitor"
]
}
Response parameters
The response will be a JSON object with a key set to params. The value of this will be an array of roles name. Each name is the identifier of a role
Retrieve a role
Retrieve a role
Request example:
curl -k -X GET -H "ZAPI_KEY: <ZAPI_KEY_STRING>"
https://<relianoid_server>:444/api/v4.0/api.cgi/rbac/roles/monitor
zcli rbac-role get monitor
GET /rbac/roles/<name>
Show the user configuration. name is the user name and it is a unique identifier.
Response parameters
The response will be a JSON object with a key set to params. The value of this will be a role struct. The keys are the permissions object, that identifies where they will act and as parameters of this object are the actions to control. If the action has the value "true", this will be allowed to the role; if the action has the value "false", the action will be blocked.
Create a role
Create a new role
Request example:
curl -k -X POST -H "ZAPI_KEY: <ZAPI_KEY_STRING>" -H 'Content-Type: application/json'
-d '{ "name":"web-monitor"}'
https://<relianoid_server>:444/api/v4.0/api.cgi/rbac/roles
zcli rbac-role create web-monitor
POST /rbac/roles
Create a role that will generate a new role from a template with all permissions set as false by default.
Request parameters
Field | Type | Description | Required |
---|---|---|---|
name | String | Role name, it is used as a unique identifier. | true |
Response parameters
The response will be a JSON object with a key set to params. The value of this will be a struct with the permissions. A permission is a key, that identifies the object where it will act and as parameters of this object are the actions to control. If the action has the value "true", this will be allowed to the role; if the action has the value "false", the action will be blocked.
Modify a role
Modify a role
Request example:
curl -k -X PUT -H 'Content-Type: application/json' -H "ZAPI_KEY: <ZAPI_KEY_STRING>"
-d ''{ "ipds":{"action":"true"}, "farm":{"maintenance":"true", "action":"true"} }'
https://<relianoid_server>:444/api/v4.0/api.cgi/rbac/roles/web-monitor
zcli rbac-role set web-monitor -section ipds -action true
zcli rbac-role set web-monitor -section farm -maintenance true -action true
PUT /rbac/users/<name>
Modify the role permissions. name is the role name and it is a unique identifier.
Request parameters:
Field | Actions | Description |
---|---|---|
alias | delete, list and modify | It defines actions to manage the alias feature. |
backup | apply, create, delete, download and upload | It defines actions to manage the backups. |
certificate | create, delete, download, show and upload | It defines actions to manage the SSL certificates. |
cluster | create, delete, maintenance and modify | It defines actions to manage the cluster. |
farm | action, create, delete, maintenance and modify | It defines actions to administrate the farms. The user only will be able to manage the farms of the user's group. |
farmguardian | modify | It defines actions to manage farm health checks. To apply a farmguardian to a farm, the required object is farm. |
interface | modify | It defines actions to administrate the network menu. The virtual interfaces are an exception, they are managed by the virtual-interfaces object. |
interface-virtual | action, create, delete and modify | It defines actions to administrate virtual interfaces. The user only will be able to manage the interfaces of the user's group. |
ipds | action and modify | It defines actions to manage the ipds rules. To apply a rule to a farm, the required object is farm. |
log | download and show | It defines actions to manage the load balancer logs. |
notification | action, modify, show and test | It defines actions to manage notifications: alerts and sent methods. |
rbac-group | create, delete, list, modify and show | It defines actions to manage the RBAC groups. |
rbac-role | create, delete, modify and show | It defines actions to manage the RBAC roles. |
rbac-user | create, delete, list, modify and show | It defines actions to manage the RBAC users. |
supportsave | download | It defines actions to manage the RELIANOID supportsave. |
system-service | modify | It defines actions to manage the remote and local services. |
vpn | action, create, delete and modify | It defines actions to administrate the vpn. |
letsencryptz | action, create, delete, modify, list and show | It defines actions to manage the Letsencrypt certificates. |
Each type of action explained below:
Action | Description |
---|---|
list | It lists the available elements of an object. true to give permission, false to remove permission. |
show | It retrieves an object and its configuration. true to give permission, false to remove permission. |
download | It downloads an object from the load balancer. true to give permission, false to remove permission. |
upload | It uploads an object to the load balancer. true to give permission, false to remove permission. |
maintenance | It modifies the status of an object between maintenance and up. true to give permission, false to remove permission. |
action | It applies an action to the object. Each object has its actions. true to give permission, false to remove permission. |
create | It creates a new element for a type of object. true to give permission, false to remove permission. |
delete | It deletes permanently an object. true to give permission, false to remove permission. |
modify | It modifies the configuration of an object. Sometimes, if the object has not the actions: create, delete or action actions, these actions are applied by modify permission. true to give permission, false to remove permission. |
menu | It shows/hides the WebGUI section. If it is true, the section will be shown to the user; If it is false, the section will be hidden to the user. |
Response parameters
The response will be a JSON object with a key set to params. The value of this will be a struct with the permissions. A permission is a key, that identifies the object where it will act and as parameters of this object are the actions to control. If the action has the value "true", this will be allowed to the role; if the action has the value "false", the action will be blocked.
Delete a role
Delete a role
Request example:
curl -k -X DELETE -H "ZAPI_KEY: <ZAPI_KEY_STRING>"
https://<relianoid_server>:444/api/v4.0/api.cgi/rbac/roles/web-monitor
zcli rbac-role delete web-monitor
DELETE /rbac/roles/<name>
Delete an RBAC role. name is the role name and it is a unique identifier.
Response example:
{
"description" : "Delete the RBAC role web-monitor",
"message" : "The RBAC role web-monitor has been deleted successful.",
"success" : "true"
}
RBAC - Groups
A group is a set of users with a role. The users can apply actions in the resources (farms and virtual interfaces) of their group.
List the groups
List all the groups
Request example:
curl -k -X GET -H "ZAPI_KEY: <ZAPI_KEY_STRING>"
https://<relianoid_server>:444/api/v4.0/api.cgi/rbac/groups
zcli rbac-group list
GET /rbac/groups
List all the RBAC groups and their settings
Response example:
{
"description" : "List the RBAC groups",
"params" : [
{
"name" : "system-admin",
"resources" : {
"farms" : [
"webHTTP",
"dns"
],
"interfaces" : [
"eth2:virt",
"eth2:vip"
]
},
"role" : "admin",
"users" : [
"john",
"monica"
]
},
{
"name" : "monitor",
"resources" : {
"farms" : [
"webHTTP",
"mailService"
],
"interfaces" : []
},
"role" : "monitor",
"users" : [
"sarah",
"kevin"
]
}
]
}
Response parameters
The response will be a JSON object with a key set to params. The value of this will be an array of group objects, each of which contains the key attributes below.
Field | Type | Description |
---|---|---|
name | String | Group name, it identifies to the group. |
resources | Object | 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. |
role | String | Role applied to the group. All users in the group inherit this role. |
users | String[] | List of users in the group. The name of the users is their unique identifiers. |
The resource object:
Field | Type | Description |
---|---|---|
farms | String[] | It is a list with the member farms of the group. |
interfaces | String[] | It is a list with the member virtual interfaces of the group. |
Retrieve a group
Retrieve a group
Request example:
curl -k -X GET -H "ZAPI_KEY: <ZAPI_KEY_STRING>"
https://<relianoid_server>:444/api/v4.0/api.cgi/rbac/groups/system-admin
zcli rbac-group get system-admin
GET /rbac/groups/<name>
Show the groups configuration. name is the user name and it is a unique identifier.
Response example:
{
"description" : "Get the group corel7",
"params" : {
"name" : "monitor",
"resources" : {
"farms" : [
"webHTTP",
"mailService"
],
"interfaces" : []
},
"role" : "monitor",
"users" : [
"sarah",
"kevin"
]
}
}
Response parameters
The response will be a JSON object with a key set to params. The value of this will be a group object, that contains the key attributes below.
Field | Type | Description |
---|---|---|
name | String | Group name, it identifies to the group. |
resources | Object | The possible values are: true, to enable the access to the load balancer through the WebGUI; or false, to not allow access through the WebGUI. |
role | String | Role applied to the group. All users in the group inherit this role. |
users | String[] | List of users in the group. The name of the users is their unique identifiers. |
The resource object:
Field | Type | Description |
---|---|---|
farms | String[] | It is a list with the member farms of the group. |
interfaces | String[] | It is a list with the member virtual interfaces of the group. |
Create a group
Create a new group
Request example:
curl -k -X POST -H "ZAPI_KEY: <ZAPI_KEY_STRING>" -H 'Content-Type: application/json'
-d '{ "name":"development"}'
https://<relianoid_server>:444/api/v4.0/api.cgi/rbac/groups
zcli rbac-group create -name development
POST /rbac/groups
Create a new group where users, resources and roles are related.
Request parameters
Field | Type | Description | Required |
---|---|---|---|
name | String | Group name, it identifies to the group. | true |
{
"description" : "Create the RBAC group, development",
"message" : "Added the RBAC group development",
"params" : {
"group" : {
"name" : "development",
"resources" : {
"farms" : [],
"interfaces" : []
},
"role" : "",
"users" : []
}
}
}
Response parameters
The response will be a JSON object with a key set to params. The value of this will be a group object, that contains the key attributes below.
Field | Type | Description |
---|---|---|
name | String | Group name, it identifies to the group. |
resources | Object | 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. |
role | String | Role applied to the group. All users in the group inherit this role. |
users | String[] | List of users in the group. The name of the users is their unique identifiers. |
The resource object:
Field | Type | Description |
---|---|---|
farms | String[] | It is a list with the member farms of the group. |
interfaces | String[] | It is a list with the member virtual interfaces of the group. |
Modify a group
Modify a group
Request example:
curl -k -X PUT -H 'Content-Type: application/json' -H "ZAPI_KEY: <ZAPI_KEY_STRING>"
-d '{ "role":"management"}'
https://<relianoid_server>:444/api/v4.0/api.cgi/rbac/groups/development
zcli rbac-group set development -role management
PUT /rbac/groups/<name>
Modify the configuration of a group. name is the group name and it is a unique identifier.
Request parameters:
Field | Type | Description | Required |
---|---|---|---|
role | String | It is the role to apply to the group. |
Response example:
{
"description" : "Create the RBAC group, development",
"message" : "Added the RBAC group development",
"params" : {
"group" : {
"name" : "development",
"resources" : {
"farms" : [],
"interfaces" : []
},
"role" : "monitor",
"users" : []
}
}
}
Response parameters
The response will be a JSON object with a key set to params. The value of this will be a group object, that contains the key attributes below.
Field | Type | Description |
---|---|---|
name | String | Group name, it identifies to the group. |
resources | Object | 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. |
role | String | Role applied to the group. All users in the group inherit this role. |
users | String[] | List of users in the group. The name of the users is their unique identifiers. |
The resource object:
Field | Type | Description |
---|---|---|
farms | String[] | It is a list with the member farms of the group. |
interfaces | String[ ] | It is a list with the member virtual interfaces of the group. |
Delete a group
Delete a user
Request example:
curl -k -X DELETE -H "ZAPI_KEY: <ZAPI_KEY_STRING>"
https://<relianoid_server>:444/api/v4.0/api.cgi/rbac/groups/development
zcli rbac-group delete development
DELETE /rbac/groups/<name>
Delete an RBAC user. name is the user name and it is a unique identifier.
Response example:
{
"description" : "Delete the RBAC group development",
"message" : "The RBAC group development has been deleted successful.",
"success" : "true"
}
Add a resource or user to a group
Add a resource or user to a group
Request example:
curl -k -X POST -H "ZAPI_KEY: <ZAPI_KEY_STRING>" -H 'Content-Type: application/json'
-d '{"name":"monica"}'
https://<relianoid_server>:444/api/v4.0/api.cgi/rbac/groups/development/users
zcli rbac-group add development -name monica
POST /rbac/groups/<name>/(interfaces|farms|users)
The URI parameter name is the group name.
Select users in the URI to add a user to the group. Select farms in the URI to add a farm to the group. Select interfaces in the URI to add a virtual interface to the group.
Request parameters
Field | Type | Description | Required |
---|---|---|---|
name | String | It is the name of the object to add to the group | true |
Response example:
{
"description" : "Add the user monica to the group development",
"message" : "Added the user monica to the group development",
"params" : {
"group" : {
"name" : "development",
"resources" : {
"farms" : [],
"interfaces" : []
},
"role" : "monitor",
"users" : [
"monica"
]
}
}
}
Response parameters
The response will be a JSON object with a key set to params. The value of this will be a group object, that contains the key attributes below.
Field | Type | Description |
---|---|---|
name | String | Group name, it identifies to the group. |
resources | Object | 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. |
role | String | Role applied to the group. All users in the group inherit this role. |
users | String[ ] | List of users in the group. The name of the users is their unique identifiers. |
The resource object:
Field | Type | Description |
---|---|---|
farms | String[ ] | It is a list with the member farms of the group. |
interfaces | String[ ] | It is a list with the member virtual interfaces of the group. |
Delete a resource or user from a group
Delete a resource or user from a group
Request example:
curl -k -X DELETE -H "ZAPI_KEY: <ZAPI_KEY_STRING>"
https://<relianoid_server>:444/api/v4.0/api.cgi/rbac/groups/development/users/monica
zcli rbac-group-user remove development monica
DELETE /rbac/groups/<name>/(interfaces|farms|users)/<name>
The first URI parameter name is the group name. The second URI parameter name is a resource or user name.
Select users in the URI to remove a user from the group. Select farms in the URI to remove a farm from the group. Select interfaces in the URI to remove a virtual interface from the group.
Response example:
{
"description" : "Removing the user monica from the group development",
"message" : "The user monica has been unlinked successful from the group development.",
"success" : "true"
}
RBAC - Authentication Services
This module allows setting the authentication servicios that RBAC will use to validate the users.
The available modules are the local load balancer system users and a external LDAP service.
Show LDAP configuration
Show LDAP configuration
Request example:
curl -k -X GET -H "ZAPI_KEY: <ZAPI_KEY_STRING>"
https://<relianoid_server>:444/api/v4.0/api.cgi/rbac/ldap
zcli rbac-services-ldap get
This call is available from version 4.0.1
GET /rbac/ldap
Show the configuration of the LDAP service
Response example:
{
"description" : "List the LDAP settings",
"params" : {
"base_dn" : "dc=relianoid,dc=com",
"bind_dn" : "cn=admin,dc=relianoid,dc=com",
"bind_password" : "********",
"filter" : "(&(objectClass=inetOrgPerson)(objectClass=posixAccount)(uid=%s))",
"host" : "ldap.relianoid.com",
"port" : "389",
"scope" : "sub",
"timeout" : "60",
"version" : "3"
}
}
Response parameters
The response will be a JSON object with the below parameters.
Field | Type | Description |
---|---|---|
base_dn | String | It is the directory from which does the search. |
bind_dn | String | It is the bind user with read permissions that will do the search. |
bind_password | String | It is the password for the bind_dn user. |
filter | String | It is the LDAP filter used to look for the user which will bed logged in. |
host | String | It is the LDAP URL or the server IP. This parameter is required to configure properly the LDAP service, if it is empty the LDAP authentication is skipt. |
port | String | It is the port where the LDAP server is listening. This filed is skipt if the host is a URL or overwrite the port. |
scope | String | It is the deep for the search: base looks for in the base_dn, one looks for one directory below of base_dn, sub looks for any directory below of base_dn. |
timeout | String | It is the timeout of the LDAP query to the server. |
version | Number | It is the LDAP version used. The possible values are 1, 2 or 3. |
Modify LDAP Configuration
Modify LDAP Configuration
Request example:
curl -k -X POST -H 'Content-Type: application/json' -H "ZAPI_KEY: <ZAPI_KEY_STRING>"
-d '{"version":"3","timeout":"60","scope":"sub","filter":"(&(objectClass=inetOrgPerson)(objectClass=posixAccount)(uid=%s))","bind_password":"admin","bind_dn":"cn=admin,dc=relianoid,dc=com","base_dn":"dc=relianoid,dc=com","host":"ldap.relianoid.com"}'
https://<relianoid_server>:444/api/v4.0/api.cgi/rbac/ldap
zcli rbac-services-ldap set -version 3 -timeout 60 -scope sub -filter (&(objectClass=inetOrgPerson)(objectClass=posixAccount)(uid=%s)) -bind_password admin -bind_dn cn=admin,dc=relianoid,dc=com -base_dn dc=relianoid,dc=com
This call is available from version 4.0.1
POST /rbac/ldap
Modify the configuration to connect with a remote LDAP service to authenticate the load balancer users.
Request parameters
Field | Type | Description |
---|---|---|
base_dn | String | It is the directory from which does the search. |
bind_dn | String | It is the bind user with read permissions that will do the search. |
bind_password | String | It is the password for the bind_dn user. |
filter | String | It is the LDAP filter used to look for the user which will bed logged in. |
host | String | It is the LDAP URL or the server IP. This parameter is required to configure properly the LDAP service, if it is empty the LDAP authentication is skipt. |
port | String | It is the port where the LDAP server is listening. This filed is skipt if the host is a URL or overwrite the port. |
scope | String | It is the deep for the search: base looks for in the base_dn, one looks for one directory below of base_dn, sub looks for any directory below of base_dn. |
timeout | String | It is the timeout of the LDAP query to the server. |
version | Number | It is the LDAP version used. The possible values are 1, 2 or 3. |
Response example:
{
"description" : "Set the LDAP settings",
"message" : "LDAP configuration was set properly",
"params" : {
"base_dn" : "dc=relianoid,dc=com",
"bind_dn" : "cn=admin,dc=relianoid,dc=com",
"bind_password" : "********",
"filter" : "(&(objectClass=inetOrgPerson)(objectClass=posixAccount)(uid=%s))",
"host" : "ldap.relianoid.com",
"port" : "389",
"scope" : "sub",
"timeout" : "60",
"version" : "3"
}
}
Response parameters
The response will be a JSON with the LDAP configuration updated.
Show Services Status
Show Services Status
Request example:
curl -k -X GET -H "ZAPI_KEY: <ZAPI_KEY_STRING>"
https://<relianoid_server>:444/api/v4.0/api.cgi/rbac/services
zcli rbac-services list
This call is available from version 4.0.1
GET /rbac/services
Show the status of the different authentication services
Response example:
{
"description" : "List the status of the authentication services",
"params" : {
"ldap" : "true",
"local" : "true"
}
}
Response parameters
The response will be a JSON object with the below parameters.
Field | Type | Description |
---|---|---|
ldap | String | It indicates if the service LDAP is enabled. If it is enabled true the authentication will be validated with a external LDAP service, else if the value is false, this feature will be skipt. |
local | String | If the value is true the authentication will be validated using the System users, if it is false, this feature will be skipt. |
Modify the status of the authentication services
Modify the status of the authentication services
Request example:
curl -k -X POST -H 'Content-Type: application/json' -H "ZAPI_KEY: <ZAPI_KEY_STRING>"
-d '{"local":"true","ldap":"true"}'
https://<relianoid_server>:444/api/v4.0/api.cgi/rbac/services
zcli rbac-service set -local true -ldap true
This call is available from version 4.0.1
POST /rbac/services
Enable/disable the authentication services.
Request parameters
Field | Type | Description |
---|---|---|
ldap | String | It indicates if the service LDAP is enabled. If it is enabled true the authentication will be validated with a external LDAP service, else if the value is false, this feature will be skipt. |
local | String | If the value is true the authentication will be validated using the System users, if it is false, this feature will be skipt. |
Response example:
{
"description" : "Modify the configuration to login using the system users",
"params" : {
"ldap" : "true",
"local" : "true"
}
}
Response parameters
The response will be a JSON object with the below parameters.
Field | Type | Description |
---|---|---|
ldap | String | It indicates if the service LDAP is enabled. If it is enabled true the authentication will be validated with a external LDAP service, else if the value is false, this feature will be skipt. |
local | String | If the value is true the authentication will be validated using the System users, if it is false, this feature will be skipt. |
Test LDAP Configuration
Test LDAP Configuration
Request example:
curl -k -X POST -H 'Content-Type: application/json' -H "ZAPI_KEY: <ZAPI_KEY_STRING>"
-d '{"action":"test"}'
https://<relianoid_server>:444/api/v4.0/api.cgi/rbac/ldap/actions
zcli rbac-services-ldap test
This call is available from version 4.0.1
POST /rbac/ldap/actions
Try a connection with the LDAP server to check the service status.
Request parameters
Field | Type | Description | Required |
---|---|---|---|
action | String | This value has to have the value test. | true |
Response example:
{
"description" : "Set the LDAP settings",
"message" : "LDAP configuration was set properly",
"params" : {
"base_dn" : "dc=relianoid,dc=com",
"bind_dn" : "cn=admin,dc=relianoid,dc=com",
"bind_password" : "********",
"filter" : "(&(objectClass=inetOrgPerson)(objectClass=posixAccount)(uid=%s))",
"host" : "ldap.relianoid.com",
"port" : "389",
"scope" : "sub",
"timeout" : "60",
"version" : "3"
}
}
Response parameters
The response will be a JSON with the LDAP configuration updated.
VPN
This module is the implementation of an VPN (Virtual Private Network).
It works establishing a tunnel and enabling communication between Local Area Network and remote Network.Applications running across a VPN may therefore benefit from the functionality, security, and management of the private network.
- ZSS: This type is a RELIANOID Site to Site VPN.
- ZTN: This type is a RELIANOID Tunnel VPN.
- ZRS: This type is a RELIANOID Remote Site VPN.
List a summary of vpns
List a summary vpns
Request example:
curl -k -X GET -H "ZAPI_KEY: <ZAPI_KEY_STRING>"
https://<relianoid_server>:444/api/v4.0/api.cgi/vpns/modules/summary
GET /vpns/modules/summary
List a summary with the vpns in the system, grouped by type.
Response example:
{
"description" : "VPN summary",
"params" : {
"zss" : [
{
"local" : "192.168.190.41",
"name" : "vpn1",
"profile" : "zss",
"remote" : "192.168.190.89"
}
],
"ztn" : [
{
"local" : "192.168.101.49",
"name" : "vpn2",
"profile" : "ztn",
"remote" : "192.168.101.46"
}
]
}
}
Response parameters
The response will be a JSON object with a key set to params. The value of this will be an array of vpns with their configurations.
Vpn Object:
Field | Type | Description |
---|---|---|
name | String | VPN descriptive name. It is used as a unique identifier for vpns. |
profile | String | Profile type, the profile available values are: zss, ztn, zrs. |
local | String | It is the local gateway which tunnel is established on. |
remote | String | It is the remote gateway which tunnel is established on. |
List all vpns
List all vps
Request example:
curl -k -X GET -H "ZAPI_KEY: <ZAPI_KEY_STRING>"
https://<relianoid_server>:444/api/v4.0/api.cgi/vpns
GET /vpns
List all available vpns
Response example:
{
"description" : "List VPNS",
"params" : [
{
"local" : "192.168.190.41",
"localnet" : "192.168.87.0/24",
"name" : "vpn1",
"profile" : "zss",
"remote" : "192.168.190.89",
"remotenet" : "192.168.89.0/24",
"status" : "down"
},
{
"local" : "192.168.101.49",
"localnet" : "192.168.87.0/24",
"name" : "vpn2",
"profile" : "ztn",
"remote" : "192.168.101.46",
"remotenet" : "192.168.89.0/24",
"status" : "down"
}
]
}
Response parameters
The response will be a JSON object with a key set to params. The value of this will be an array of vpn resume objects, each of which contains the key attributes below.
VPN Object:
Field | Type | Description |
---|---|---|
name | String | VPN descriptive name. It is used as a unique identifier for vpns. |
profile | String | Profile type, the profile available values are: zss, ztn, zrs. |
status | String | vpn status. The available status values are: down, the vpn is not established; needed restart, the vpn is established but it is pending of a restart action; up, the vpn is established; connecting, the vpn is trying to be established, ipsec_down, the ipsec component is down, tunnel_down the tunnel component is down. |
local | String | It is the local gateway which tunnel is established on. |
remote | String | It is the remote gateway which tunnel is established on. |
localnet | String | It is the local network which can be accessed by this VPN. |
remotenet | String | It is the remote network which can accessed by this VPN. |
Delete a VPN
Delete a VPN
Request example:
curl --tlsv1 -k -X DELETE -H 'Content-Type: application/json' -H "ZAPI_KEY: <ZAPI_KEY_STRING>"
https://<relianoid_server>:444/api/v4.0/api.cgi/vpns/vpn_name
DELETE /vpns/<vpn_name>
Delete a vpn through its vpn name identifier.
Response example:
{
"description" : "Delete VPN vpn_name",
"message" : "The VPN vpn_name has been deleted.",
"success" : "true"
}
Set an action in a VPN
Set an action in a VPN
Request example:
curl -k -X POST -H 'Content-Type: application/json' -H "ZAPI_KEY: <ZAPI_KEY_STRING>"
-d '{"action":"stop"}' https://<relianoid_server>:444/api/v4.0/api.cgi/vpns/vpn_name/actions
POST /vpns/<vpn_name>/actions
Apply an action to a vpn, see the Request parameters table for actions.
Request parameters
Field | Type | Description |
---|---|---|
action | String | The action to execute, the possibilities are: stop, the vpn will be stopped; start, the vpn will be started; restart, the vpn will be stopped and started automatically. |
Response example:
{
"description" : "Set a new action in vpn_name",
"params" : [
{
"action" : "stop",
"status" : "down"
}
]
}
Response parameters
If there are no issues in the configuration then ZAPI will return the requested action and the status.
VPN ZSS
The ZSS profile is a RELIANOID Site to Site VPN.
Retrieve VPN by name
Retrieve VPN by name
Request example:
curl -k -X GET -H "ZAPI_KEY: <ZAPI_KEY_STRING>"
https://<relianoid_server>:444/api/v4.0/api.cgi/vpns/vpn_name
NI: zcli vpn get vpn_name
GET /vpns/<vpn_name>
Show all configuration about a given VPN.
Response example:
{
"description" : "List VPN vpn3",
"params" : {
"auth" : "secret",
"local" : "192.168.190.41",
"localnet" : "192.168.87.0/24",
"name" : "vpn3",
"p1authen" : [
"sha256"
],
"p1dhgroup" : [
"modp1024"
],
"p1encrypt" : [
"aes128",
"aes256"
],
"p2authen" : [
"sha256"
],
"p2dhgroup" : [
"modp1024"
],
"p2encrypt" : [
"aes256"
],
"p2prfunc" : [
"prfmd5"
],
"p2protocol" : "esp",
"password" : "misharedkey",
"profile" : "zss",
"remote" : "192.168.190.89",
"remotenet" : "192.168.89.0/24",
"status" : "down"
}
}
Response parameters
The response will be a JSON object with a key set to params.
Field | Type | Description |
---|---|---|
name | String | VPN descriptive name. It is used as a unique identifier for vpns. |
profile | String | Profile type, the profile available values are: zss. |
status | String | vpn status. The available status values are: down, the vpn is not established; needed restart, the vpn is established but it is pending of a restart action; up, the vpn is established and the route is configured; connecting, the vpn is trying to be established; route_down, the ipsec connection is up and the route is not configured. |
local | String | It is the local gateway which tunnel is established on. |
remote | String | It is the remote gateway which tunnel is established on. |
localnet | String | It is the local network which can be accessed by this VPN. |
remotenet | String | It is the remote network which can accessed by this VPN. |
auth | String | The authentication method. For shared key is secret. |
password | String | The shared key used in both gateways. |
p1authen | String[] | IPsec Phase1 authentication. The available authentication values are: md5, sha1, sha256, sha384, sha512, aesxcbc, aes128gmac, aes192gmac, aes256gmac. |
p1encrypt | String[] | IPsec Phase1 encryption. The available cipher values are: aes128, aes192, aes256, aes128gmac, aes192gmac, aes256gmac, 3des, blowfish128, blowfish192, blowfish256, camellia128, camellia192, camellia256. |
p1group | String[] | IPsec Phase1 DH Group. The available group values are: modp768, modp1024, modp1536, modp2048, modp3072, modp4096, modp6144, modp8192. |
p2protocol | String | Ipsec Phase2 protocol type. For Encapsulating Security Payload is esp. |
p2authen | String[] | IPsec Phase2 authentication. The available authentication values are: md5, sha1, sha256, sha384, sha512, aesxcbc, aes128gmac, aes192gmac, aes256gmac. |
p2encrypt | String[] | IPsec Phase2 encryption. The available cipher values are: aes128, aes192, aes256, aes128gmac, aes192gmac, aes256gmac, 3des, blowfish128, blowfish192, blowfish256, camellia128, camellia192, camellia256. |
p2prfunc | String[] | IPsec Phase2 Pseudo Random Function. The available prfunction values are: prfmd5, prfsha1, prfsha256, prfsha384, prfsha512, prfaes, prfaesxcbc, prfaescmac. |
Create a new VPN
Create a new VPN
Request example:
curl -k -X POST -H 'Content-Type: application/json' -H "ZAPI_KEY: <ZAPI_KEY_STRING>"
-d '{"name":"vpn_name","profile":"zss","local":"192.168.101.47","remote":"192.168.101.46","localnet":"192.168.88.0/24","remotenet":"192.168.89.0/24","auth":"secret","password":"misharedkey"}' https://zva600005:444/zapi/v4.1/zapi.cgi/vpns
NI: zcli vpn create vpn_name
POST /vpns
Create a new ZSS VPN.
Request parameters
Field | Type | Description | Required |
---|---|---|---|
name | String | VPN descriptive name. It is used as a unique identifier. | true |
profile | String | The profile of the created Farm. For ZSS VPN is zss. | true |
local | String | It is the local gateway which tunnel is established on. | true |
remote | String | It is the remote gateway which tunnel is established on. | true |
localnet | String | It is the local network which can be accessed by this VPN. | true |
remotenet | String | It is the remote network which can accessed by this VPN. | true |
auth | String | The authentication method. For shared key is secret. | true |
password | String | The shared key used in both gateways. | true |
p1authen | String[] | IPsec Phase1 authentication. The available authentication values are: md5, sha1, sha256, sha384, sha512, aesxcbc, aes128gmac, aes192gmac, aes256gmac. | true |
p1encrypt | String[] | IPsec Phase1 encryption. The available cipher values are: aes128, aes192, aes256, aes128gmac, aes192gmac, aes256gmac, 3des, blowfish128, blowfish192, blowfish256, camellia128, camellia192, camellia256. | true |
p1dhgroup | String[] | IPsec Phase1 DH Group. The available group values are: modp768, modp1024, modp1536, modp2048, modp3072, modp4096, modp6144, modp8192. | true |
p2protocol | String | Ipsec Phase2 protocol type. For Encapsulating Security Payload is esp. | true |
p2authen | String[] | IPsec Phase2 authentication. The available authentication values are: md5, sha1, sha256, sha384, sha512, aesxcbc, aes128gmac, aes192gmac, aes256gmac. | true |
p2encrypt | String[] | IPsec Phase2 encryption. The available cipher values are: aes128, aes192, aes256, aes128gmac, aes192gmac, aes256gmac, 3des, blowfish128, blowfish192, blowfish256, camellia128, camellia192, camellia256. | true |
p2dhgroup | String[] | IPsec Phase2 DH Group. The available group values are: modp768, modp1024, modp1536, modp2048, modp3072, modp4096, modp6144, modp8192. | true |
p2prfunc | String[] | IPsec Phase2 Pseudo Random Function. The available prfunction values are: prfmd5, prfsha1, prfsha256, prfsha384, prfsha512, prfaes, prfaesxcbc, prfaescmac. | true |
Response example:
{
"description" : "Create ZSS VPN vpn3",
"params" : {
"auth" : "secret",
"local" : "192.168.190.41",
"localnet" : "192.168.87.0/24",
"name" : "vpn3",
"p1authen" : [
"sha256"
],
"p1dhgroup" : [
"modp1024"
],
"p1encrypt" : [
"aes128",
"aes256"
],
"p2authen" : [
"sha256"
],
"p2dhgroup" : [
"modp1024"
],
"p2encrypt" : [
"aes128",
"aes256"
],
"p2prfunc" : [
"prfmd5"
],
"p2protocol" : "esp",
"password" : "misharedkey",
"profile" : "zss",
"remote" : "192.168.190.89",
"remotenet" : "192.168.89.0/24",
"status" : "down"
}
}
Response parameters
The response will be a JSON object with a key set to params.
Field | Type | Description |
---|---|---|
name | String | VPN descriptive name. It is used as a unique identifier. |
profile | String | The profile of the created Farm. For ZSS VPN is zss. |
local | String | It is the local gateway which tunnel is established on. |
remote | String | It is the remote gateway which tunnel is established on. |
localnet | String | It is the local network which can be accessed by this VPN. |
remotenet | String | It is the remote network which can accessed by this VPN. |
auth | String | The authentication method. For shared key is secret. |
password | String | The shared key used in both gateways. |
p1authen | String[] | IPsec Phase1 authentication. The available authentication values are: md5, sha1, sha256, sha384, sha512, aesxcbc, aes128gmac, aes192gmac, aes256gmac. |
p1encrypt | String[] | IPsec Phase1 encryption. The available cipher values are: aes128, aes192, aes256, aes128gmac, aes192gmac, aes256gmac, 3des, blowfish128, blowfish192, blowfish256, camellia128, camellia192, camellia256. |
p1dhgroup | String[] | IPsec Phase1 DH Group. The available group values are: modp768, modp1024, modp1536, modp2048, modp3072, modp4096, modp6144, modp8192. |
p2protocol | String | Ipsec Phase2 protocol type. For Encapsulating Security Payload is esp. |
p2authen | String[] | IPsec Phase2 authentication. The available authentication values are: md5, sha1, sha256, sha384, sha512, aesxcbc, aes128gmac, aes192gmac, aes256gmac. |
p2encrypt | String[] | IPsec Phase2 encryption. The available cipher values are: aes128, aes192, aes256, aes128gmac, aes192gmac, aes256gmac, 3des, blowfish128, blowfish192, blowfish256, camellia128, camellia192, camellia256. |
p2dhgroup | String[] | IPsec Phase2 DH Group. The available group values are: modp768, modp1024, modp1536, modp2048, modp3072, modp4096, modp6144, modp8192. |
p2prfunc | String[] | IPsec Phase2 Pseudo Random Function. The available prfunction values are: prfmd5, prfsha1, prfsha256, prfsha384, prfsha512, prfaes, prfaesxcbc, prfaescmac. |
status | String | vpn status. The available status values are: down, the vpn is not established; needed restart, the vpn is established but it is pending of a restart action; up, the vpn is established and the route is configured; connecting, the vpn is trying to be established; route_down, the ipsec connection is up and the route is not configured. |
Modify a VPN
Modify a VPN
Request example:
curl -k -X PUT -H 'Content-Type: application/json' -H "ZAPI_KEY: <ZAPI_KEY_STRING>"
-d '{"localnet":"192.168.87.0/24","remotenet" : "192.168.89.0/24","local" : "192.168.190.41","remote" : "192.168.190.89","password":"misharedkey","p1encrypt":["aes128","aes256"],"p1authen":["sha256"],"p1dhgroup":["modp1024"],"p2encrypt":["aes128","aes256"],"p2authen":["sha256"],"p2dhgroup":["modp1024"],"p2prfunc":["prfmd5"]}'
NI: zcli vpn set vpn_name
PUT /vpns/<vpnname>
Modify a new ZSS VPN.
Request parameters
Field | Type | Description | Required |
---|---|---|---|
local | String | It is the local gateway which tunnel is established on. | false |
remote | String | It is the remote gateway which tunnel is established on. | false |
localnet | String | It is the local network which can be accessed by this VPN. | false |
remotenet | String | It is the remote network which can accessed by this VPN. | false |
password | String | The shared key used in both gateways. | false |
p1authen | String[] | IPsec Phase1 authentication. The available authentication values are: md5, sha1, sha256, sha384, sha512, aesxcbc, aes128gmac, aes192gmac, aes256gmac. | false |
p1encrypt | String[] | IPsec Phase1 encryption. The available cipher values are: aes128, aes192, aes256, aes128gmac, aes192gmac, aes256gmac, 3des, blowfish128, blowfish192, blowfish256, camellia128, camellia192, camellia256. | false |
p1dhgroup | String[] | IPsec Phase1 DH Group. The available group values are: modp768, modp1024, modp1536, modp2048, modp3072, modp4096, modp6144, modp8192. | false |
p2authen | String[] | IPsec Phase2 authentication. The available authentication values are: md5, sha1, sha256, sha384, sha512, aesxcbc, aes128gmac, aes192gmac, aes256gmac. | false |
p2encrypt | String[] | IPsec Phase2 encryption. The available cipher values are: aes128, aes192, aes256, aes128gmac, aes192gmac, aes256gmac, 3des, blowfish128, blowfish192, blowfish256, camellia128, camellia192, camellia256. | false |
p2prfunc | String[] | IPsec Phase2 Pseudo Random Function. The available prfunction values are: prfmd5, prfsha1, prfsha256, prfsha384, prfsha512, prfaes, prfaesxcbc, prfaescmac. | false |
p2dhgroup | String[] | IPsec Phase2 DH Group. The available group values are: modp768, modp1024, modp1536, modp2048, modp3072, modp4096, modp6144, modp8192. | false |
Response example:
{
"description" : "Modify ZSS VPN zss",
"params" : {
"auth" : "secret",
"local" : "192.168.101.49",
"localnet" : "192.168.87.0/24",
"name" : "zss",
"p1authen" : [
"sha1"
],
"p1dhgroup" : [
"modp2048"
],
"p1encrypt" : [
"aes128"
],
"p2authen" : [
"sha1"
],
"p2dhgroup" : [
"modp2048"
],
"p2encrypt" : [
"aes128"
],
"p2prfunc" : [
"prfmd5"
],
"p2protocol" : "esp",
"password" : "misharedkey",
"profile" : "zss",
"remote" : "192.168.101.56",
"remotenet" : "192.168.89.0/24",
"status" : "need restart"
}
}
Response parameters
The response will be a JSON object with a key set to params.
Field | Type | Description | Required |
---|---|---|---|
name | String | VPN descriptive name. It is used as a unique identifier. | true |
profile | String | The profile of the created Farm. For ZSS VPN is zss. | true |
local | String | It is the local gateway which tunnel is established on. | true |
remote | String | It is the remote gateway which tunnel is established on. | true |
localnet | String | It is the local network which can be accessed by this VPN. | true |
remotenet | String | It is the remote network which can accessed by this VPN. | true |
auth | String | The authentication method. For shared key is secret. | true |
password | String | The shared key used in both gateways. | true |
p1authen | String[] | IPsec Phase1 authentication. The available authentication values are: md5, sha1, sha256, sha384, sha512, aesxcbc, aes128gmac, aes192gmac, aes256gmac. | true |
p1encrypt | String[] | IPsec Phase1 encryption. The available cipher values are: aes128, aes192, aes256, aes128gmac, aes192gmac, aes256gmac, 3des, blowfish128, blowfish192, blowfish256, camellia128, camellia192, camellia256. | true |
p1dhgroup | String[] | IPsec Phase1 DH Group. The available group values are: modp768, modp1024, modp1536, modp2048, modp3072, modp4096, modp6144, modp8192. | true |
p2protocol | String | Ipsec Phase2 protocol type. For Encapsulating Security Payload is esp. | true |
p2authen | String[] | IPsec Phase2 authentication. The available authentication values are: md5, sha1, sha256, sha384, sha512, aesxcbc, aes128gmac, aes192gmac, aes256gmac. | true |
p2encrypt | String[] | IPsec Phase2 encryption. The available cipher values are: aes128, aes192, aes256, aes128gmac, aes192gmac, aes256gmac, 3des, blowfish128, blowfish192, blowfish256, camellia128, camellia192, camellia256. | true |
p2dhgroup | String[] | IPsec Phase2 DH Group. The available group values are: modp768, modp1024, modp1536, modp2048, modp3072, modp4096, modp6144, modp8192. | true |
p2prfunc | String[] | IPsec Phase2 Pseudo Random Function. The available prfunction values are: prfmd5, prfsha1, prfsha256, prfsha384, prfsha512, prfaes, prfaesxcbc, prfaescmac. | true |
status | String | vpn status. The available status values are: down, the vpn is not established; needed restart, the vpn is established but it is pending of a restart action; up, the vpn is established and the route is configured; connecting, the vpn is trying to be established; route_down, the ipsec connection is up and the route is not configured. |
VPN ZTN
The ZTN profile is a RELIANOID Tunnel VPN.
Retrieve VPN by name
Retrieve VPN by name
Request example:
curl -k -X GET -H "ZAPI_KEY: <ZAPI_KEY_STRING>"
https://<relianoid_server>:444/api/v4.0/api.cgi/vpns/vpn_name
NI: zcli vpn get vpn_name
GET /vpns/<vpn_name>
Show all configuration about a given VPN.
Response example:
{
"description" : "List VPN ztn",
"params" : {
"auth" : "secret",
"local" : "192.168.101.49",
"localip" : "192.168.87.90",
"localmask" : "255.255.255.0",
"localnet" : "192.168.87.0/24",
"localtunip" : "10.10.10.1",
"localtunmask" : "255.255.255.0",
"name" : "ztn",
"p1authen" : [
"sha1"
],
"p1dhgroup" : [
"modp2048"
],
"p1encrypt" : [
"aes128",
"aes256"
],
"p2authen" : [
"sha1"
],
"p2dhgroup" : [
"modp2048"
],
"p2encrypt" : [
"aes128",
"aes256"
],
"p2prfunc" : [
"prfmd5"
],
"p2protocol" : "esp",
"password" : "misharedkey",
"profile" : "ztn",
"remote" : "192.168.101.46",
"remoteip" : "192.168.89.46",
"remotemask" : "255.255.255.0",
"remotenet" : "192.168.89.0/24",
"remotetunip" : "10.10.10.2",
"status" : "down"
}
}
Response parameters
The response will be a JSON object with a key set to params.
Field | Type | Description |
---|---|---|
name | String | VPN descriptive name. It is used as a unique identifier for vpns. |
profile | String | Profile type, the profile available values are: ztn. |
local | String | It is the local gateway which tunnel is established on. |
remote | String | It is the remote gateway which tunnel is established on. |
localip | String | It is the local network ip which can be accessed by this VPN. |
localnetmask | String | It is the local network netmask which can be accessed by this VPN. |
remoteip | String | It is the remote network ip which can accessed by this VPN. |
remotenetmask | String | It is the remote network netmask which can accessed by this VPN. |
auth | String | The authentication method. For shared key is secret. |
password | String | The shared key used in both gateways. |
p1authen | String[] | IPsec Phase1 authentication. The available authentication values are: md5, sha1, sha256, sha384, sha512, aesxcbc, aes128gmac, aes192gmac, aes256gmac. |
p1encrypt | String[] | IPsec Phase1 encryption. The available cipher values are: aes128, aes192, aes256, aes128gmac, aes192gmac, aes256gmac, 3des, blowfish128, blowfish192, blowfish256, camellia128, camellia192, camellia256. |
p1group | String[] | IPsec Phase1 DH Group. The available group values are: modp768, modp1024, modp1536, modp2048, modp3072, modp4096, modp6144, modp8192. |
p2protocol | String | Ipsec Phase2 protocol type. For Encapsulating Security Payload is esp. |
p2authen | String[] | IPsec Phase2 authentication. The available authentication values are: md5, sha1, sha256, sha384, sha512, aesxcbc, aes128gmac, aes192gmac, aes256gmac. |
p2encrypt | String[] | IPsec Phase2 encryption. The available cipher values are: aes128, aes192, aes256, aes128gmac, aes192gmac, aes256gmac, 3des, blowfish128, blowfish192, blowfish256, camellia128, camellia192, camellia256. |
p2prfunc | String[] | IPsec Phase2 Pseudo Random Function. The available prfunction values are: prfmd5, prfsha1, prfsha256, prfsha384, prfsha512, prfaes, prfaesxcbc, prfaescmac. |
status | String | vpn status. The available status values are: down, the vpn is not established and the tunnel is down; needed restart, the vpn is established but it is pending of a restart action; up, the vpn is establishedi and the tunnel is up; connecting, the vpn is trying to be established; ipsec_down, the ipsec connection is down an the tunnel is up;tunnel_down, the ipsec connection is up and the tunnel is down. |
localtunip | String | It is the local tunnel ip which can be accessed by this VPN. |
localtunmask | String | It is the local tunnel netmask which can be accessed by this VPN. |
remotetunip | String | It is the remote network ip which can accessed by this VPN. |
Create a new VPN
Create a new VPN
Request example:
curl -k -X POST -H 'Content-Type: application/json' -H "ZAPI_KEY: <ZAPI_KEY_STRING>"
-d '{"name":"ztn","profile":"ztn","local":"192.168.101.49","remote":"192.168.101.46","localip":"192.168.87.90","localmask":"255.255.255.0","remoteip":"192.168.89.46","remotemask":"255.255.255.0","auth":"secret","password":"misharedkey","p1authen":["sha1"],"p1encrypt":["aes128","aes256"],"p1dhgroup":["modp2048"],"p2protocol":"esp","p2authen":["sha1"],"p2encrypt":["aes128","aes256"],"p2dhgroup":["modp2048"],"p2prfunc":["prfmd5"],"localtunip":"10.10.10.1","localtunmask":"255.255.255.0","remotetunip":"10.10.10.2"}'
https://<relianoid_server>:444/api/v4.0/api.cgi/vpns
NI: zcli vpn create vpn_name
POST /vpns
Create a new ZTN VPN.
Request parameters
Field | Type | Description | Required |
---|---|---|---|
name | String | VPN descriptive name. It is used as a unique identifier. | true |
profile | String | The profile of the created Farm. For ZTN VPN is ztn. | true |
local | String | It is the local gateway which tunnel is established on. | true |
remote | String | It is the remote gateway which tunnel is established on. | true |
localip | String | It is the local network ip which can be accessed by this VPN. | true |
localnetmask | String | It is the local network netmask which can be accessed by this VPN. | |
remoteip | String | It is the remote network ip which can accessed by this VPN. | true |
remotenetmask | String | It is the remote network netmask which can accessed by this VPN. | true |
auth | String | The authentication method. For shared key is secret. | true |
password | String | The shared key used in both gateways. | true |
p1authen | String[] | IPsec Phase1 authentication. The available authentication values are: md5, sha1, sha256, sha384, sha512, aesxcbc, aes128gmac, aes192gmac, aes256gmac. | true |
p1encrypt | String[] | IPsec Phase1 encryption. The available cipher values are: aes128, aes192, aes256, aes128gmac, aes192gmac, aes256gmac, 3des, blowfish128, blowfish192, blowfish256, camellia128, camellia192, camellia256. | true |
p1group | String[] | IPsec Phase1 DH Group. The available group values are: modp768, modp1024, modp1536, modp2048, modp3072, modp4096, modp6144, modp8192. | true |
p2protocol | String | Ipsec Phase2 protocol type. For Encapsulating Security Payload is esp. | true |
p2authen | String[] | IPsec Phase2 authentication. The available authentication values are: md5, sha1, sha256, sha384, sha512, aesxcbc, aes128gmac, aes192gmac, aes256gmac. | true |
p2encrypt | String[] | IPsec Phase2 encryption. The available cipher values are: aes128, aes192, aes256, aes128gmac, aes192gmac, aes256gmac, 3des, blowfish128, blowfish192, blowfish256, camellia128, camellia192, camellia256. | true |
p2prfunc | String[] | IPsec Phase2 Pseudo Random Function. The available prfunction values are: prfmd5, prfsha1, prfsha256, prfsha384, prfsha512, prfaes, prfaesxcbc, prfaescmac. | true |
localtunip | String | It is the local tunnel ip which can be accessed by this VPN. | true |
localtunmask | String | It is the local tunnel netmask which can be accessed by this VPN. | true |
remotetunip | String | It is the remote network ip which can accessed by this VPN. | true |
Response example:
{
"description" : "Create ZTN VPN ztn",
"params" : {
"auth" : "secret",
"local" : "192.168.101.49",
"localip" : "192.168.87.90",
"localmask" : "255.255.255.0",
"localnet" : "192.168.87.0/24",
"localtunip" : "10.10.10.1",
"localtunmask" : "255.255.255.0",
"name" : "ztn",
"p1authen" : [
"sha1"
],
"p1dhgroup" : [
"modp2048"
],
"p1encrypt" : [
"aes128",
"aes256"
],
"p2authen" : [
"sha1"
],
"p2dhgroup" : [
"modp2048"
],
"p2encrypt" : [
"aes128",
"aes256"
],
"p2prfunc" : [
"prfmd5"
],
"p2protocol" : "esp",
"password" : "misharedkey",
"profile" : "ztn",
"remote" : "192.168.101.46",
"remoteip" : "192.168.89.46",
"remotemask" : "255.255.255.0",
"remotenet" : "192.168.89.0/24",
"remotetunip" : "10.10.10.2",
"status" : "down"
}
}
Response parameters
The response will be a JSON with all values updated. See the response example for more information.
Field | Type | Description |
---|---|---|
name | String | VPN descriptive name. It is used as a unique identifier for vpns. |
profile | String | Profile type, the profile available values are: ztn. |
local | String | It is the local gateway which tunnel is established on. |
remote | String | It is the remote gateway which tunnel is established on. |
localip | String | It is the local network ip which can be accessed by this VPN. |
localnetmask | String | It is the local network netmask which can be accessed by this VPN. |
remoteip | String | It is the remote network ip which can accessed by this VPN. |
remotenetmask | String | It is the remote network netmask which can accessed by this VPN. |
auth | String | The authentication method. For shared key is secret. |
password | String | The shared key used in both gateways. |
p1authen | String[] | IPsec Phase1 authentication. The available authentication values are: md5, sha1, sha256, sha384, sha512, aesxcbc, aes128gmac, aes192gmac, aes256gmac. |
p1encrypt | String[] | IPsec Phase1 encryption. The available cipher values are: aes128, aes192, aes256, aes128gmac, aes192gmac, aes256gmac, 3des, blowfish128, blowfish192, blowfish256, camellia128, camellia192, camellia256. |
p1group | String[] | IPsec Phase1 DH Group. The available group values are: modp768, modp1024, modp1536, modp2048, modp3072, modp4096, modp6144, modp8192. |
p2protocol | String | Ipsec Phase2 protocol type. For Encapsulating Security Payload is esp. |
p2authen | String[] | IPsec Phase2 authentication. The available authentication values are: md5, sha1, sha256, sha384, sha512, aesxcbc, aes128gmac, aes192gmac, aes256gmac. |
p2encrypt | String[] | IPsec Phase2 encryption. The available cipher values are: aes128, aes192, aes256, aes128gmac, aes192gmac, aes256gmac, 3des, blowfish128, blowfish192, blowfish256, camellia128, camellia192, camellia256. |
p2prfunc | String[] | IPsec Phase2 Pseudo Random Function. The available prfunction values are: prfmd5, prfsha1, prfsha256, prfsha384, prfsha512, prfaes, prfaesxcbc, prfaescmac. |
status | String | vpn status. The available status values are: down, the vpn is not established and the tunnel is down; needed restart, the vpn is established but it is pending of a restart action; up, the vpn is established, the tunnel is up and the route is configured; connecting, the vpn is trying to be established; ipsec_down, the ipsec connection is down an the tunnel is up;tunnel_down, the ipsec connection is up and the tunnel is down;route_down, the ipsec connection is up, the tunnel is up and the route is not configured. |
localtunip | String | It is the local tunnel ip which can be accessed by this VPN. |
localtunmask | String | It is the local tunnel netmask which can be accessed by this VPN. |
remotetunip | String | It is the remote network ip which can accessed by this VPN. |
Modify a VPN
Modify a VPN
Request example:
curl -k -X PUT -H 'Content-Type: application/json' -H "ZAPI_KEY: <ZAPI_KEY_STRING>"
-d '{"name":"ztn","profile":"ztn","local":"192.168.101.49","remote":"192.168.101.46","localip":"192.168.87.90","localmask":"255.255.255.0","remoteip":"192.168.89.46","remotemask":"255.255.255.0","auth":"secret","password":"misharedkey","p1authen":["sha1"],"p1encrypt":["aes128","aes256"],"p1dhgroup":["modp2048"],"p2protocol":"esp","p2authen":["sha1"],"p2encrypt":["aes128","aes256"],"p2dhgroup":["modp2048"],"p2prfunc":["prfmd5"],"localtunip":"10.10.10.1","localtunmask":"255.255.255.0","remotetunip":"10.10.10.2"}'
https://<relianoid_server>:444/api/v4.0/api.cgi/vpns/vpn_name
NI: zcli vpn set vpn_name
PUT /vpns/<vpnname>
Modify a new ZSS VPN.
Request parameters
Field | Type | Description | Required |
---|---|---|---|
local | String | It is the local gateway which tunnel is established on. | false |
remote | String | It is the remote gateway which tunnel is established on. | false |
localip | String | It is the local network ip which can be accessed by this VPN. | true |
localnetmask | String | It is the local network netmask which can be accessed by this VPN. | |
remoteip | String | It is the remote network ip which can accessed by this VPN. | true |
remotenetmask | String | It is the remote network netmask which can accessed by this VPN. | true |
password | String | The shared key used in both gateways. | false |
p1authen | Array | IPsec Phase1 authentication. The available authentication values are: md5, sha1, sha256, sha384, sha512, aesxcbc, aes128gmac, aes192gmac, aes256gmac. | false |
p1encrypt | Array | IPsec Phase1 encryption. The available cipher values are: aes128, aes192, aes256, aes128gmac, aes192gmac, aes256gmac, 3des, blowfish128, blowfish192, blowfish256, camellia128, camellia192, camellia256. | false |
p1group | Array | IPsec Phase1 DH Group. The available group values are: modp768, modp1024, modp1536, modp2048, modp3072, modp4096, modp6144, modp8192. | false |
p2protocol | String | Ipsec Phase2 protocol type. For Encapsulating Security Payload is esp. | false |
p2authen | Array | IPsec Phase2 authentication. The available authentication values are: md5, sha1, sha256, sha384, sha512, aesxcbc, aes128gmac, aes192gmac, aes256gmac. | false |
p2encrypt | Array | IPsec Phase2 encryption. The available cipher values are: aes128, aes192, aes256, aes128gmac, aes192gmac, aes256gmac, 3des, blowfish128, blowfish192, blowfish256, camellia128, camellia192, camellia256. | false |
p2prfunc | Array | IPsec Phase2 Pseudo Random Function. The available prfunction values are: prfmd5, prfsha1, prfsha256, prfsha384, prfsha512, prfaes, prfaesxcbc, prfaescmac. | false |
status | String | vpn status. The available status values are: down, the vpn is not established; needed restart, the vpn is established but it is pending of a restart action; | |
localtunip | String | It is the local tunnel ip which can be accessed by this VPN. | true |
localtunmask | String | It is the local tunnel netmask which can be accessed by this VPN. | true |
remotetunip | String | It is the remote network ip which can accessed by this VPN. | true |
Response example:
{
"description" : "Modify ZTN VPN ztn",
"params" : {
"auth" : "secret",
"local" : "192.168.101.49",
"localip" : "192.168.87.90",
"localmask" : "255.255.255.0",
"localnet" : "192.168.87.0/24",
"localtunip" : "10.10.10.1",
"localtunmask" : "255.255.255.0",
"name" : "ztn",
"p1authen" : [
"sha1"
],
"p1dhgroup" : [
"modp2048"
],
"p1encrypt" : [
"aes128",
"aes256"
],
"p2authen" : [
"sha1"
],
"p2dhgroup" : [
"modp2048"
],
"p2encrypt" : [
"aes128",
"aes256"
],
"p2prfunc" : [
"prfmd5"
],
"p2protocol" : "esp",
"password" : "misharedkey",
"profile" : "ztn",
"remote" : "192.168.101.46",
"remoteip" : "192.168.89.46",
"remotemask" : "255.255.255.0",
"remotenet" : "192.168.89.0/24",
"remotetunip" : "10.10.10.2",
"status" : "ipsec down"
}
}
Response parameters
The response will be a JSON with all values updated. See the response example for more information.
Field | Type | Description |
---|---|---|
name | String | VPN descriptive name. It is used as a unique identifier for vpns. |
profile | String | Profile type, the profile available values are: ztn. |
local | String | It is the local gateway which tunnel is established on. |
remote | String | It is the remote gateway which tunnel is established on. |
localip | String | It is the local network ip which can be accessed by this VPN. |
localnetmask | String | It is the local network netmask which can be accessed by this VPN. |
remoteip | String | It is the remote network ip which can accessed by this VPN. |
remotenetmask | String | It is the remote network netmask which can accessed by this VPN. |
auth | String | The authentication method. For shared key is secret. |
password | String | The shared key used in both gateways. |
p1authen | String[] | IPsec Phase1 authentication. The available authentication values are: md5, sha1, sha256, sha384, sha512, aesxcbc, aes128gmac, aes192gmac, aes256gmac. |
p1encrypt | String[] | IPsec Phase1 encryption. The available cipher values are: aes128, aes192, aes256, aes128gmac, aes192gmac, aes256gmac, 3des, blowfish128, blowfish192, blowfish256, camellia128, camellia192, camellia256. |
p1group | String[] | IPsec Phase1 DH Group. The available group values are: modp768, modp1024, modp1536, modp2048, modp3072, modp4096, modp6144, modp8192. |
p2protocol | String | Ipsec Phase2 protocol type. For Encapsulating Security Payload is esp. |
p2authen | String[] | IPsec Phase2 authentication. The available authentication values are: md5, sha1, sha256, sha384, sha512, aesxcbc, aes128gmac, aes192gmac, aes256gmac. |
p2encrypt | String[] | IPsec Phase2 encryption. The available cipher values are: aes128, aes192, aes256, aes128gmac, aes192gmac, aes256gmac, 3des, blowfish128, blowfish192, blowfish256, camellia128, camellia192, camellia256. |
p2prfunc | String[] | IPsec Phase2 Pseudo Random Function. The available prfunction values are: prfmd5, prfsha1, prfsha256, prfsha384, prfsha512, prfaes, prfaesxcbc, prfaescmac. |
status | String | vpn status. The available status values are: down, the vpn is not established and the tunnel is down; needed restart, the vpn is established but it is pending of a restart action; up, the vpn is established, the tunnel is up and the route is configured; connecting, the vpn is trying to be established; ipsec_down, the ipsec connection is down an the tunnel is up;tunnel_down, the ipsec connection is up and the tunnel is down;route_down, the ipsec connection is up, the tunnel is up and the route is not configured. |
localtunip | String | It is the local tunnel ip which can be accessed by this VPN. |
localtunmask | String | It is the local tunnel netmask which can be accessed by this VPN. |
remotetunip | String | It is the remote network ip which can accessed by this VPN. |
VPN ZRS
The ZRS profile is a RELIANOID Remote Server VPN.
Retrieve VPN by name
Retrieve VPN by name
Request example:
curl -k -X GET -H "ZAPI_KEY: <ZAPI_KEY_STRING>"
https://<relianoid_server>:444/api/v4.0/api.cgi/vpns/vpn_name
NI: zcli vpn get vpn_name
GET /vpns/<vpn_name>
Show all configuration about a given VPN.
Response example:
{
"description" : "List VPN zrs",
"params" : {
"auth" : "secret",
"local" : "192.168.101.49",
"localip" : "192.168.87.41",
"localmask" : "255.255.255.0",
"localnet" : "192.168.87.0/24",
"localtunip" : "10.10.10.1",
"localtunmask" : "255.255.255.0",
"name" : "zrs",
"p1authen" : [
"sha1"
],
"p1dhgroup" : [
"modp2048"
],
"p1encrypt" : [
"aes128",
"aes256"
],
"p2authen" : [
"sha1"
],
"p2dhgroup" : [],
"p2encrypt" : [
"aes128",
"aes256"
],
"p2prfunc" : [],
"p2protocol" : "esp",
"password" : "misharedkey",
"profile" : "zrs",
"remotetunrange" : "10.10.10.30-10.10.10.50",
"status" : "ipsec down",
"vpnuser" : []
}
}
Response parameters
The response will be a JSON object with a key set to params.
Field | Type | Description |
---|---|---|
name | String | VPN descriptive name. It is used as a unique identifier for vpns. |
profile | String | Profile type, the profile available values are: ztn. |
local | String | It is the local gateway which tunnel is established on. |
localip | String | It is the local network ip which can be accessed by this VPN. |
localnetmask | String | It is the local network netmask which can be accessed by this VPN. |
auth | String | The authentication method. For shared key is secret. |
password | String | The shared key used in both gateways. |
p1authen | String[] | IPsec Phase1 authentication. The available authentication values are: md5, sha1, sha256, sha384, sha512, aesxcbc, aes128gmac, aes192gmac, aes256gmac. |
p1encrypt | String[] | IPsec Phase1 encryption. The available cipher values are: aes128, aes192, aes256, aes128gmac, aes192gmac, aes256gmac, 3des, blowfish128, blowfish192, blowfish256, camellia128, camellia192, camellia256. |
p1dhgroup | String[] | IPsec Phase1 DH Group. The available group values are: modp768, modp1024, modp1536, modp2048, modp3072, modp4096, modp6144, modp8192. |
p2protocol | String | Ipsec Phase2 protocol type. For Encapsulating Security Payload is esp. |
p2authen | String[] | IPsec Phase2 authentication. The available authentication values are: md5, sha1, sha256, sha384, sha512, aesxcbc, aes128gmac, aes192gmac, aes256gmac. |
p2encrypt | String[] | IPsec Phase2 encryption. The available cipher values are: aes128, aes192, aes256, aes128gmac, aes192gmac, aes256gmac, 3des, blowfish128, blowfish192, blowfish256, camellia128, camellia192, camellia256. |
p2dhgroup | String[] | IPsec Phase2 DH Group. The available group values are: modp768, modp1024, modp1536, modp2048, modp3072, modp4096, modp6144, modp8192. |
p2prfunc | String[] | IPsec Phase2 Pseudo Random Function. The available prfunction values are: prfmd5, prfsha1, prfsha256, prfsha384, prfsha512, prfaes, prfaesxcbc, prfaescmac. |
status | String | vpn status. The available status values are: down, the vpn is not established and the tunnel is down; needed restart, the vpn is established but it is pending of a restart action; up, the vpn is established, the tunnel is up and the route is configured; connecting, the vpn is trying to be established; ipsec_down, the ipsec connection is down an the tunnel is up;tunnel_down, the ipsec connection is up and the tunnel is down; route_down, the ipsec connection is up, the tunnel is up and the route is not configured. |
localtunip | String | It is the local tunnel ip which can be accessed by this VPN. |
localtunmask | String | It is the local tunnel netmask which can be accessed by this VPN. |
remotetunrange | String | It is the remote network ip range which can accessed by this VPN. |
vpnuser | String[] | It is the user list who can authenticate with this VPN. |
Create a new VPN
Create a new VPN
Request example:
curl -k -X POST -H 'Content-Type: application/json' -H "ZAPI_KEY: <ZAPI_KEY_STRING>"
-d '{"name":"zrs","profile":"zrs","local":"192.168.101.49","localip":"192.168.87.41","localmask":"255.255.255.0","auth":"secret","password":"misharedkey","p1authen":["sha1"],"p1encrypt":["aes128","es256"],"p1dhgroup":["modp2048"],"p2protocol":"esp","p2authen":["sha1"],"p2encrypt":["aes128","aes256"],"localtunip":"10.10.10.1","localtunmask":"255.255.255.0","remotetunrange":"10.10.10.30-10.10.10.50"}'
https://<relianoid_server>:444/api/v4.0/api.cgi/vpns
NI: zcli vpn create vpn_name
POST /vpns
Create a new ZRS VPN.
Request parameters
Field | Type | Description | Required |
---|---|---|---|
name | String | VPN descriptive name. It is used as a unique identifier. | true |
profile | String | The profile of the created Farm. For ZRS VPN is zrs. | true |
local | String | It is the local gateway which tunnel is established on. | true |
localip | String | It is the local network ip which can be accessed by this VPN. | true |
localmask | String | It is the local network netmask which can be accessed by this VPN. | |
auth | String | The authentication method. For shared key is secret. | true |
password | String | The shared key used in both gateways. | true |
p1authen | String[] | IPsec Phase1 authentication. The available authentication values are: md5, sha1, sha256, sha384, sha512, aesxcbc, aes128gmac, aes192gmac, aes256gmac. | true |
p1encrypt | String[] | IPsec Phase1 encryption. The available cipher values are: aes128, aes192, aes256, aes128gmac, aes192gmac, aes256gmac, 3des, blowfish128, blowfish192, blowfish256, camellia128, camellia192, camellia256. | true |
p1dhgroup | String[] | IPsec Phase1 DH Group. The available group values are: modp768, modp1024, modp1536, modp2048, modp3072, modp4096, modp6144, modp8192. | true |
p2protocol | String[] | Ipsec Phase2 protocol type. For Encapsulating Security Payload is esp. | true |
p2authen | String[] | IPsec Phase2 authentication. The available authentication values are: md5, sha1, sha256, sha384, sha512, aesxcbc, aes128gmac, aes192gmac, aes256gmac. | true |
p2encrypt | String[] | IPsec Phase2 encryption. The available cipher values are: aes128, aes192, aes256, aes128gmac, aes192gmac, aes256gmac, 3des, blowfish128, blowfish192, blowfish256, camellia128, camellia192, camellia256. | true |
p2dhgroup | String[] | IPsec Phase2 DH Group. The available group values are: modp768, modp1024, modp1536, modp2048, modp3072, modp4096, modp6144, modp8192. | |
p2prfunc | String[] | IPsec Phase2 Pseudo Random Function. The available prfunction values are: prfmd5, prfsha1, prfsha256, prfsha384, prfsha512, prfaes, prfaesxcbc, prfaescmac. | true |
localtunip | String | It is the local tunnel ip which can be accessed by this VPN. | true |
localtunmask | String | It is the local tunnel netmask which can be accessed by this VPN. | true |
remotetunrange | String | It is the remote network ip range which can accessed by this VPN. | true |
Response example:
{
"description" : "Create ZRS VPN zrs",
"params" : {
"auth" : "secret",
"local" : "192.168.101.49",
"localip" : "192.168.87.41",
"localmask" : "255.255.255.0",
"localnet" : "192.168.87.0/24",
"localtunip" : "10.10.10.1",
"localtunmask" : "255.255.255.0",
"name" : "zrs",
"p1authen" : [
"sha1"
],
"p1dhgroup" : [
"modp2048"
],
"p1encrypt" : [
"aes128",
"aes256"
],
"p2authen" : [
"sha1"
],
"p2dhgroup" : [],
"p2encrypt" : [
"aes128",
"aes256"
],
"p2prfunc" : [],
"p2protocol" : "esp",
"password" : "misharedkey",
"profile" : "zrs",
"remotetunrange" : "10.10.10.30-10.10.10.50",
"status" : "ipsec down",
"vpnuser" : []
}
}
Response parameters
The response will be a JSON object with a key set to params.
Field | Type | Description |
---|---|---|
name | String | VPN descriptive name. It is used as a unique identifier for vpns. |
profile | String | Profile type, the profile available values are: ztn. |
local | String | It is the local gateway which tunnel is established on. |
localip | String | It is the local network ip which can be accessed by this VPN. |
localmask | String | It is the local network netmask which can be accessed by this VPN. |
auth | String | The authentication method. For shared key is secret. |
password | String | The shared key used in both gateways. |
p1authen | String[] | IPsec Phase1 authentication. The available authentication values are: md5, sha1, sha256, sha384, sha512, aesxcbc, aes128gmac, aes192gmac, aes256gmac. |
p1encrypt | String[] | IPsec Phase1 encryption. The available cipher values are: aes128, aes192, aes256, aes128gmac, aes192gmac, aes256gmac, 3des, blowfish128, blowfish192, blowfish256, camellia128, camellia192, camellia256. |
p1dhgroup | String[] | IPsec Phase1 DH Group. The available group values are: modp768, modp1024, modp1536, modp2048, modp3072, modp4096, modp6144, modp8192. |
p2protocol | String | Ipsec Phase2 protocol type. For Encapsulating Security Payload is esp. |
p2authen | String[] | IPsec Phase2 authentication. The available authentication values are: md5, sha1, sha256, sha384, sha512, aesxcbc, aes128gmac, aes192gmac, aes256gmac. |
p2encrypt | String[] | IPsec Phase2 encryption. The available cipher values are: aes128, aes192, aes256, aes128gmac, aes192gmac, aes256gmac, 3des, blowfish128, blowfish192, blowfish256, camellia128, camellia192, camellia256. |
p2dhgroup | String[] | IPsec Phase2 DH Group. The available group values are: modp768, modp1024, modp1536, modp2048, modp3072, modp4096, modp6144, modp8192. |
p2prfunc | String[] | IPsec Phase2 Pseudo Random Function. The available prfunction values are: prfmd5, prfsha1, prfsha256, prfsha384, prfsha512, prfaes, prfaesxcbc, prfaescmac. |
status | String | vpn status. The available status values are: down, the vpn is not established and the tunnel is down; needed restart, the vpn is established but it is pending of a restart action; up, the vpn is established, the tunnel is up and the route is configured; connecting, the vpn is trying to be established; ipsec_down, the ipsec connection is down an the tunnel is up;tunnel_down, the ipsec connection is up and the tunnel is down; route_down, the ipsec connection is up, the tunnel is up and the route is not configured. |
localtunip | String | It is the local tunnel ip which can be accessed by this VPN. |
localtunmask | String | It is the local tunnel netmask which can be accessed by this VPN. |
remotetunrange | String | It is the remote network ip range which can accessed by this VPN. |
vpnuser | String[] | It is the user list who can authenticate with this VPN. |
Modify a VPN
Modify a VPN
Request example:
curl -k -X PUT -H 'Content-Type: application/json' -H "ZAPI_KEY: <ZAPI_KEY_STRING>"
-d '{"local":"192.168.101.49","localip":"192.168.87.41","localmask":"255.255.255.0","auth":"secret","password":"misharedkey","p1authen":["sha1"],"p1encrypt":["aes128","es256"],"p1dhgroup":["modp2048"],"p2protocol":"esp","p2authen":["sha1"],"p2encrypt":["aes128","aes256"],"localtunip":"10.10.10.1","localtunmask":"255.255.255.0","remotetunrange":"10.10.10.30-10.10.10.50"}'
https://<relianoid_server>:444/api/v4.0/api.cgi/vpns/vpn_name
NI: zcli vpn set vpn_name
PUT /vpns/<vpnname>
Modify a ZRS VPN.
Request parameters
Field | Type | Description | Required |
---|---|---|---|
local | String | It is the local gateway which tunnel is established on. | false |
localip | String | It is the local network ip which can be accessed by this VPN. | true |
localmask | String | It is the local network netmask which can be accessed by this VPN. | |
password | String | The shared key used in both gateways. | false |
p1authen | String[] | IPsec Phase1 authentication. The available authentication values are: md5, sha1, sha256, sha384, sha512, aesxcbc, aes128gmac, aes192gmac, aes256gmac. | false |
p1encrypt | String[] | IPsec Phase1 encryption. The available cipher values are: aes128, aes192, aes256, aes128gmac, aes192gmac, aes256gmac, 3des, blowfish128, blowfish192, blowfish256, camellia128, camellia192, camellia256. | false |
p1dhgroup | String[] | IPsec Phase1 DH Group. The available group values are: modp768, modp1024, modp1536, modp2048, modp3072, modp4096, modp6144, modp8192. | false |
p2protocol | String | Ipsec Phase2 protocol type. For Encapsulating Security Payload is esp. | false |
p2authen | String[] | IPsec Phase2 authentication. The available authentication values are: md5, sha1, sha256, sha384, sha512, aesxcbc, aes128gmac, aes192gmac, aes256gmac. | false |
p2encrypt | String[] | IPsec Phase2 encryption. The available cipher values are: aes128, aes192, aes256, aes128gmac, aes192gmac, aes256gmac, 3des, blowfish128, blowfish192, blowfish256, camellia128, camellia192, camellia256. | false |
p2prfunc | String[] | IPsec Phase2 Pseudo Random Function. The available prfunction values are: prfmd5, prfsha1, prfsha256, prfsha384, prfsha512, prfaes, prfaesxcbc, prfaescmac. | false |
localtunip | String | It is the local tunnel ip which can be accessed by this VPN. | true |
localtunmask | String | It is the local tunnel netmask which can be accessed by this VPN. | true |
remotetunip | String | It is the remote network ip which can accessed by this VPN. | true |
remotetunrange | String | It is the remote network ip range which can accessed by this VPN. | true |
Response example:
{
"description" : "Modify ZRS VPN zrs",
"params" : {
"auth" : "secret",
"local" : "192.168.101.49",
"localip" : "192.168.87.41",
"localmask" : "255.255.255.0",
"localnet" : "192.168.87.0/24",
"localtunip" : "10.10.10.1",
"localtunmask" : "255.255.255.0",
"name" : "zrs",
"p1authen" : [
"sha1"
],
"p1dhgroup" : [
"modp2048"
],
"p1encrypt" : [
"aes128",
"aes256"
],
"p2authen" : [
"sha1"
],
"p2dhgroup" : [],
"p2encrypt" : [
"aes128",
"aes256"
],
"p2prfunc" : [],
"p2protocol" : "esp",
"password" : "misharedkey",
"profile" : "zrs",
"remotetunrange" : "10.10.10.30-10.10.10.50",
"status" : "need restart",
"vpnuser" : []
}
}
Response parameters
The response will be a JSON with all values updated. See the response example for more information.
Field | Type | Description |
---|---|---|
name | String | VPN descriptive name. It is used as a unique identifier for vpns. |
profile | String | Profile type, the profile available values are: ztn. |
local | String | It is the local gateway which tunnel is established on. |
localip | String | It is the local network ip which can be accessed by this VPN. |
localmask | String | It is the local network netmask which can be accessed by this VPN. |
auth | String | The authentication method. For shared key is secret. |
password | String | The shared key used in both gateways. |
p1authen | String[] | IPsec Phase1 authentication. The available authentication values are: md5, sha1, sha256, sha384, sha512, aesxcbc, aes128gmac, aes192gmac, aes256gmac. |
p1encrypt | String[] | IPsec Phase1 encryption. The available cipher values are: aes128, aes192, aes256, aes128gmac, aes192gmac, aes256gmac, 3des, blowfish128, blowfish192, blowfish256, camellia128, camellia192, camellia256. |
p1dhgroup | String[] | IPsec Phase1 DH Group. The available group values are: modp768, modp1024, modp1536, modp2048, modp3072, modp4096, modp6144, modp8192. |
p2protocol | String | Ipsec Phase2 protocol type. For Encapsulating Security Payload is esp. |
p2authen | String[] | IPsec Phase2 authentication. The available authentication values are: md5, sha1, sha256, sha384, sha512, aesxcbc, aes128gmac, aes192gmac, aes256gmac. |
p2encrypt | String[] | IPsec Phase2 encryption. The available cipher values are: aes128, aes192, aes256, aes128gmac, aes192gmac, aes256gmac, 3des, blowfish128, blowfish192, blowfish256, camellia128, camellia192, camellia256. |
p2dhgroup | String[] | IPsec Phase2 DH Group. The available group values are: modp768, modp1024, modp1536, modp2048, modp3072, modp4096, modp6144, modp8192. |
p2prfunc | String[] | IPsec Phase2 Pseudo Random Function. The available prfunction values are: prfmd5, prfsha1, prfsha256, prfsha384, prfsha512, prfaes, prfaesxcbc, prfaescmac. |
status | String | vpn status. The available status values are: down, the vpn is not established and the tunnel is down; needed restart, the vpn is established but it is pending of a restart action; up, the vpn is established, the tunnel is up and the route is configured; connecting, the vpn is trying to be established; ipsec_down, the ipsec connection is down an the tunnel is up;tunnel_down, the ipsec connection is up and the tunnel is down; route_down, the ipsec connection is up, the tunnel is up and the route is not configured. |
localtunip | String | It is the local tunnel ip which can be accessed by this VPN. |
localtunmask | String | It is the local tunnel netmask which can be accessed by this VPN. |
remotetunrange | String | It is the remote network ip range which can accessed by this VPN. |
vpnuser | String[] | It is the user list who can authenticate with this VPN. |
Create a new ZRS VPN User
Create a new ZRS VPN User
Request example:
curl -k -X POST -H "ZAPI_KEY: <ZAPI_KEY_STRING>"
-d '{"vpnuser":"newuser","vpnpass":"password"}'
https://<relianoid_server>:444/api/v4.0/api.cgi/vpns/vpn_name/users
NI : zcli vpn-user create vpn_name -vpnuser newuser -vpnpass password
POST /vpns/vpn_name/users
Create a new ZRS VPN user.
Request parameters
Field | Type | Description | Required |
---|---|---|---|
vpnuser | String | User name to use with the ZRS VPN | true |
vpnpass | String | Password for the user name | true |
Response example:
{
"description" : "Create ZRS VPN User",
"params" : {
"auth" : "secret",
"local" : "192.168.101.49",
"localip" : "192.168.87.41",
"localmask" : "255.255.255.0",
"localnet" : "192.168.87.0/24",
"localtunip" : "10.10.10.1",
"localtunmask" : "255.255.255.0",
"name" : "zrs",
"p1authen" : [
"sha1"
],
"p1dhgroup" : [
"modp2048"
],
"p1encrypt" : [
"aes128",
"aes256"
],
"p2authen" : [
"sha1"
],
"p2dhgroup" : [],
"p2encrypt" : [
"aes128",
"aes256"
],
"p2prfunc" : [],
"p2protocol" : "esp",
"password" : "misharedkey",
"profile" : "zrs",
"remotetunrange" : "10.10.10.30-10.10.10.50",
"status" : "ipsec down",
"vpnuser" : [
"newuser"
]
},
"message" : "The VPN user newuser has been created successfully."
}
Response parameters
The response will be a JSON with all values updated. See the response example for more information.
Field | Type | Description |
---|---|---|
name | String | VPN descriptive name. It is used as a unique identifier for vpns. |
profile | String | Profile type, the profile available values are: ztn. |
local | String | It is the local gateway which tunnel is established on. |
localip | String | It is the local network ip which can be accessed by this VPN. |
localmask | String | It is the local network netmask which can be accessed by this VPN. |
auth | String | The authentication method. For shared key is secret. |
password | String | The shared key used in both gateways. |
p1authen | String[] | IPsec Phase1 authentication. The available authentication values are: md5, sha1, sha256, sha384, sha512, aesxcbc, aes128gmac, aes192gmac, aes256gmac. |
p1encrypt | String[] | IPsec Phase1 encryption. The available cipher values are: aes128, aes192, aes256, aes128gmac, aes192gmac, aes256gmac, 3des, blowfish128, blowfish192, blowfish256, camellia128, camellia192, camellia256. |
p1dhgroup | String[] | IPsec Phase1 DH Group. The available group values are: modp768, modp1024, modp1536, modp2048, modp3072, modp4096, modp6144, modp8192. |
p2protocol | String | Ipsec Phase2 protocol type. For Encapsulating Security Payload is esp. |
p2authen | String[] | IPsec Phase2 authentication. The available authentication values are: md5, sha1, sha256, sha384, sha512, aesxcbc, aes128gmac, aes192gmac, aes256gmac. |
p2encrypt | String[] | IPsec Phase2 encryption. The available cipher values are: aes128, aes192, aes256, aes128gmac, aes192gmac, aes256gmac, 3des, blowfish128, blowfish192, blowfish256, camellia128, camellia192, camellia256. |
p2dhgroup | String[] | IPsec Phase2 DH Group. The available group values are: modp768, modp1024, modp1536, modp2048, modp3072, modp4096, modp6144, modp8192. |
p2prfunc | String[] | IPsec Phase2 Pseudo Random Function. The available prfunction values are: prfmd5, prfsha1, prfsha256, prfsha384, prfsha512, prfaes, prfaesxcbc, prfaescmac. |
status | String | vpn status. The available status values are: down, the vpn is not established and the tunnel is down; needed restart, the vpn is established but it is pending of a restart action; up, the vpn is established, the tunnel is up and the route is configured; connecting, the vpn is trying to be established; ipsec_down, the ipsec connection is down an the tunnel is up;tunnel_down, the ipsec connection is up and the tunnel is down; route_down, the ipsec connection is up, the tunnel is up and the route is not configured. |
localtunip | String | It is the local tunnel ip which can be accessed by this VPN. |
localtunmask | String | It is the local tunnel netmask which can be accessed by this VPN. |
remotetunrange | String | It is the remote network ip range which can accessed by this VPN. |
vpnuser | String[] | It is the user list who can authenticate with this VPN. |
Delete a ZRS VPN User
Delete ZRS VPN User
Request example:
curl -k -X DELETE -H "ZAPI_KEY: <ZAPI_KEY_STRING>"
https://<relianoid_server>:444/api/v4.0/api.cgi/vpns/<vpn_name>/users/<user_name>
NI : zcli vpn-user remove vpn_name user_name
DELETE /vpns/<vpn_name>/users/<user_name>
Delete a ZRS VPN user.
Response example:
{
"description" : "Delete ZRS VPN User",
"message" : "The VPN user newuser has been deleted.",
"params" : {
"auth" : "secret",
"local" : "192.168.101.44",
"localip" : "192.168.88.44",
"localmask" : "255.255.255.0",
"localnet" : "192.168.88.0/24",
"localtunip" : "10.10.10.1",
"localtunmask" : "255.255.255.0",
"name" : "test-zrs",
"p1authen" : [
"sha1"
],
"p1dhgroup" : [
"modp2048"
],
"p1encrypt" : [
"aes128",
"aes256"
],
"p2authen" : [
"sha1"
],
"p2dhgroup" : [],
"p2encrypt" : [
"aes128",
"aes256"
],
"p2prfunc" : [],
"p2protocol" : "esp",
"password" : "misharedkey",
"profile" : "zrs",
"remotetunrange" : "10.10.10.30-10.10.10.50",
"status" : "down",
"vpnuser" : [
"otheruser"
]
}
}
Response parameters
The response will be a JSON with all values updated. See the response example for more information.
Field | Type | Description |
---|---|---|
name | String | VPN descriptive name. It is used as a unique identifier for vpns. |
profile | String | Profile type, the profile available values are: ztn. |
local | String | It is the local gateway which tunnel is established on. |
localip | String | It is the local network ip which can be accessed by this VPN. |
localmask | String | It is the local network netmask which can be accessed by this VPN. |
auth | String | The authentication method. For shared key is secret. |
password | String | The shared key used in both gateways. |
p1authen | String[] | IPsec Phase1 authentication. The available authentication values are: md5, sha1, sha256, sha384, sha512, aesxcbc, aes128gmac, aes192gmac, aes256gmac. |
p1encrypt | String[] | IPsec Phase1 encryption. The available cipher values are: aes128, aes192, aes256, aes128gmac, aes192gmac, aes256gmac, 3des, blowfish128, blowfish192, blowfish256, camellia128, camellia192, camellia256. |
p1dhgroup | String[] | IPsec Phase1 DH Group. The available group values are: modp768, modp1024, modp1536, modp2048, modp3072, modp4096, modp6144, modp8192. |
p2protocol | String | Ipsec Phase2 protocol type. For Encapsulating Security Payload is esp. |
p2authen | String[] | IPsec Phase2 authentication. The available authentication values are: md5, sha1, sha256, sha384, sha512, aesxcbc, aes128gmac, aes192gmac, aes256gmac. |
p2encrypt | String[] | IPsec Phase2 encryption. The available cipher values are: aes128, aes192, aes256, aes128gmac, aes192gmac, aes256gmac, 3des, blowfish128, blowfish192, blowfish256, camellia128, camellia192, camellia256. |
p2dhgroup | String[] | IPsec Phase2 DH Group. The available group values are: modp768, modp1024, modp1536, modp2048, modp3072, modp4096, modp6144, modp8192. |
p2prfunc | String[] | IPsec Phase2 Pseudo Random Function. The available prfunction values are: prfmd5, prfsha1, prfsha256, prfsha384, prfsha512, prfaes, prfaesxcbc, prfaescmac. |
status | String | vpn status. The available status values are: down, the vpn is not established and the tunnel is down; needed restart, the vpn is established but it is pending of a restart action; up, the vpn is established, the tunnel is up and the route is configured; connecting, the vpn is trying to be established; ipsec_down, the ipsec connection is down an the tunnel is up;tunnel_down, the ipsec connection is up and the tunnel is down; route_down, the ipsec connection is up, the tunnel is up and the route is not configured. |
localtunip | String | It is the local tunnel ip which can be accessed by this VPN. |
localtunmask | String | It is the local tunnel netmask which can be accessed by this VPN. |
remotetunrange | String | It is the remote network ip range which can accessed by this VPN. |
vpnuser | String[] | It is the user list who can authenticate with this VPN. |
Modify a ZRS VPN User
Modify ZRS VPN User
Request example:
curl -k -X PUT -H "ZAPI_KEY: <ZAPI_KEY_STRING>"
-d '{"vpnpass":"newpassword"}'
https://<relianoid_server>:444/api/v4.0/api.cgi/vpns/<vpn_name>/users/<user_name>
NI : zcli vpn-user set vpn_name user_name -vpnpass newpassword
PUT /vpns/<vpn_name>/users/<user_name>
Modify a ZRS VPN user.
Request parameters
Field | Type | Description | Required |
---|---|---|---|
vpnpass | String | Password for the user name | true |
Response example:
{
"description" : "Modify ZRS VPN User",
"message" : "Some parameters have been changed in VPN user newuser.",
"params" : {
"auth" : "secret",
"local" : "192.168.101.44",
"localip" : "192.168.88.44",
"localmask" : "255.255.255.0",
"localnet" : "192.168.88.0/24",
"localtunip" : "10.10.10.1",
"localtunmask" : "255.255.255.0",
"name" : "test-zrs",
"p1authen" : [
"sha1"
],
"p1dhgroup" : [
"modp2048"
],
"p1encrypt" : [
"aes128",
"aes256"
],
"p2authen" : [
"sha1"
],
"p2dhgroup" : [],
"p2encrypt" : [
"aes128",
"aes256"
],
"p2prfunc" : [],
"p2protocol" : "esp",
"password" : "misharedkey",
"profile" : "zrs",
"remotetunrange" : "10.10.10.30-10.10.10.50",
"status" : "down",
"vpnuser" : [
"newuser",
"otheruser"
]
}
}
Response parameters
The response will be a JSON with all values updated. See the response example for more information.
Field | Type | Description |
---|---|---|
name | String | VPN descriptive name. It is used as a unique identifier for vpns. |
profile | String | Profile type, the profile available values are: ztn. |
local | String | It is the local gateway which tunnel is established on. |
localip | String | It is the local network ip which can be accessed by this VPN. |
localmask | String | It is the local network netmask which can be accessed by this VPN. |
auth | String | The authentication method. For shared key is secret. |
password | String | The shared key used in both gateways. |
p1authen | String[] | IPsec Phase1 authentication. The available authentication values are: md5, sha1, sha256, sha384, sha512, aesxcbc, aes128gmac, aes192gmac, aes256gmac. |
p1encrypt | String[] | IPsec Phase1 encryption. The available cipher values are: aes128, aes192, aes256, aes128gmac, aes192gmac, aes256gmac, 3des, blowfish128, blowfish192, blowfish256, camellia128, camellia192, camellia256. |
p1dhgroup | String[] | IPsec Phase1 DH Group. The available group values are: modp768, modp1024, modp1536, modp2048, modp3072, modp4096, modp6144, modp8192. |
p2protocol | String | Ipsec Phase2 protocol type. For Encapsulating Security Payload is esp. |
p2authen | String[] | IPsec Phase2 authentication. The available authentication values are: md5, sha1, sha256, sha384, sha512, aesxcbc, aes128gmac, aes192gmac, aes256gmac. |
p2encrypt | String[] | IPsec Phase2 encryption. The available cipher values are: aes128, aes192, aes256, aes128gmac, aes192gmac, aes256gmac, 3des, blowfish128, blowfish192, blowfish256, camellia128, camellia192, camellia256. |
p2dhgroup | String[] | IPsec Phase2 DH Group. The available group values are: modp768, modp1024, modp1536, modp2048, modp3072, modp4096, modp6144, modp8192. |
p2prfunc | String[] | IPsec Phase2 Pseudo Random Function. The available prfunction values are: prfmd5, prfsha1, prfsha256, prfsha384, prfsha512, prfaes, prfaesxcbc, prfaescmac. |
status | String | vpn status. The available status values are: down, the vpn is not established and the tunnel is down; needed restart, the vpn is established but it is pending of a restart action; up, the vpn is established, the tunnel is up and the route is configured; connecting, the vpn is trying to be established; ipsec_down, the ipsec connection is down an the tunnel is up;tunnel_down, the ipsec connection is up and the tunnel is down; route_down, the ipsec connection is up, the tunnel is up and the route is not configured. |
localtunip | String | It is the local tunnel ip which can be accessed by this VPN. |
localtunmask | String | It is the local tunnel netmask which can be accessed by this VPN. |
remotetunrange | String | It is the remote network ip range which can accessed by this VPN. |
vpnuser | String[] | It is the user list who can authenticate with this VPN. |