Filters¶
aXAPI filters work with GET methods to specify that only certain records of interest will appear in the responses. Without filters, all the records are returned by default.
The aXAPI filter mechanisms provide two aspects of control for all the GET methods. Both of the following mechanisms can work together.
- Paging Mechanism - handles a huge amount of data records under an aXAPI endpoint.
- Field Filtering Mechanism - picks up special data records that match specified fields.
The stats and oper filters work a bit differently for the GET methods, so their usage is limited to a subset of URIs.
- Statistics Data Filtering - for use with URIs that include the
/statsendpoint.- Oper Endpoint Filtering - for use with URIs that include the
/operendpoint.
The slot filters are used in chassis platforms to collect data from both Processing Units (PU) 1 and 2, as well as to aggregate statistical and basic operational data.
- Slot Filtering - for use with
/statsand/operendpoints, which includes ‘slot’ filter.
The user tag filters are limited to a subset of SSL Insight objects. They are used to automatically mark an object that is created in the SSLi Services GUI.
- User Tag Filtering - for use with SSLi objects that include the “user-tag”:”Security” property.
Paging Mechanism¶
The paging mechanism helps to break up large responses into more manageable chunks.
The filter keywords total, start, and count are reserved for the paging mechanism.
- total - shows how many records currently exist.
- start - indicates an index from which those records will be returned.
- count - indicates a limitation. It controls how many records should be returned.
For example, if there are four slb servers, the total=true filter shows the total count of slb servers:
curl -k GET https://10.10.10.10/axapi/v3/slb/server?total=true \
-H "Content-Type:application/json" \
-H "Authorization: A10 c223169c3ab18f9e3826b9df215c2b"
#Filtered Response
{
"total-count":4
}
If there are four slb servers, the start=3 filter shows the server at index number 3: [d1, d2, s1, s2]:
curl -k GET https://10.10.10.10/axapi/v3/slb/server?start=3 \
-H "Content-Type:application/json" \
-H "Authorization: A10 c223169c3ab18f9e3826b9df215c2b"
#Filtered Response
{
"server-list": [
{
"name":"s2",
"host":"1.1.1.2",
"action":"enable",
"template-server":"default",
"health-check-disable":0,
"conn-limit":8000000,
"no-logging":0,
"weight":1,
"slow-start":0,
"spoofing-cache":0,
"stats-data-action":"stats-data-enable",
"extended-stats":0,
"uuid":"a7ec1a00-3270-11df-a8af-000d480a65d0",
"a10-url":"/axapi/v3/slb/server/s2"
}
]
}
If there are four slb servers, the start=1&count=1 filters show a list of servers starting at index number 1, but only a list of 1: [d1, d2, s1, s2]:
curl -k GET https://10.10.10.10/axapi/v3/slb/server?start=1&count=1 \
-H "Content-Type:application/json" \
-H "Authorization: A10 c223169c3ab18f9e3826b9df215c2b"
#Filtered Response
{
"server-list": [
{
"name":"d2",
"host":"1.1.1.4",
"action":"enable",
"template-server":"default",
"health-check-disable":0,
"conn-limit":8000000,
"no-logging":0,
"weight":1,
"slow-start":0,
"spoofing-cache":0,
"stats-data-action":"stats-data-enable",
"extended-stats":0,
"uuid":"b059da1a-3270-11df-a8af-000d480a65d0",
"a10-url":"/axapi/v3/slb/server/d2"
}
]
}
Field Filtering Mechanism¶
Field filtering is used to select a matched set of instances as returned records. A filtering keyword is simply a field keyword defined within the schema file. Currently, only the string type field can be supported. The matching rule is that a field’s value contains the specified string from filter.
For example, the field name is used as a filter to find slb servers whose names contain the character s:
curl -k GET https://10.10.10.10/axapi/v3/slb/server?name=s \
-H "Content-Type:application/json" \
-H "Authorization: A10 c223169c3ab18f9e3826b9df215c2b"
#Filtered Response
{
"server-list": [
{
"name":"s1",
"host":"1.1.1.1",
"action":"disable",
"template-server":"default",
"health-check-disable":0,
"conn-limit":8000000,
"no-logging":0,
"weight":1,
"slow-start":0,
"spoofing-cache":0,
"stats-data-action":"stats-data-enable",
"extended-stats":0,
"uuid":"a25672e8-3270-11df-a8af-000d480a65d0",
"a10-url":"/axapi/v3/slb/server/s1"
},
{
"name":"s2",
"host":"1.1.1.2",
"action":"enable",
"template-server":"default",
"health-check-disable":0,
"conn-limit":8000000,
"no-logging":0,
"weight":1,
"slow-start":0,
"spoofing-cache":0,
"stats-data-action":"stats-data-enable",
"extended-stats":0,
"uuid":"a7ec1a00-3270-11df-a8af-000d480a65d0",
"a10-url":"/axapi/v3/slb/server/s2"
}
]
}
The combination of multiple fields as filters means an AND relationship, such as using the name & action fields to find slb servers that start with s and are enabled:
curl -k GET https://10.10.10.10/axapi/v3/slb/server?name=s&action=enable \
-H "Content-Type:application/json" \
-H "Authorization: A10 c223169c3ab18f9e3826b9df215c2b"
#Filtered Response
{
"server-list": [
{
"name":"s2",
"host":"1.1.1.2",
"action":"enable",
"template-server":"default",
"health-check-disable":0,
"conn-limit":8000000,
"no-logging":0,
"weight":1,
"slow-start":0,
"spoofing-cache":0,
"stats-data-action":"stats-data-enable",
"extended-stats":0,
"uuid":"a7ec1a00-3270-11df-a8af-000d480a65d0",
"a10-url":"/axapi/v3/slb/server/s2"
}
]
}
It is possible to use field filtering and paging mechanisms together, such as using the name field with the total & count filters to find the total number of slb servers whose names start with s, starting from index number 0, but only a list of 1:
curl -k GET https://10.10.10.10/axapi/v3/slb/server?name=s&start=0&count=1 \
-H "Content-Type:application/json" \
-H "Authorization: A10 c223169c3ab18f9e3826b9df215c2b"
#Filtered Response
{
"server-list": [
{
"name":"s1",
"host":"1.1.1.1",
"action":"disable",
"template-server":"default",
"health-check-disable":0,
"conn-limit":8000000,
"no-logging":0,
"weight":1,
"slow-start":0,
"spoofing-cache":0,
"stats-data-action":"stats-data-enable",
"extended-stats":0,
"uuid":"a25672e8-3270-11df-a8af-000d480a65d0",
"a10-url":"/axapi/v3/slb/server/s1"
}
]
}
Statistics Data Filtering¶
Some schema files define extended statistics data. To get this part of the data, you need to use the corresponding filter within the URIs that include the /stats endpoint. For example, slb virtual port has such statistics data, according to its L7 protocol.
Basic Statistics
The basic statistics are available at the statistics data URI: /axapi/v3/slb/virtual-server/{name}/port/{port-number}+{protocol}/stats:
curl -k GET https://10.10.10.10/axapi/v3/slb/virtual-server/vs1/port/80+http/stats \
-H "Content-Type:application/json" \
-H "Authorization: A10 c223169c3ab18f9e3826b9df215c2b"
#Response
{
"port": {
"stats": {
"curr_conn": 0,
"total_l4_conn": 0,
"total_l7_conn": 0,
"total_tcp_conn": 0,
"total_conn": 0,
"total_fwd_bytes": 0,
"total_fwd_pkts": 0,
"total_rev_bytes": 0,
"total_rev_pkts": 0,
"total_dns_pkts": 0,
"total_mf_dns_pkts": 0,
"es_total_failure_actions": 0,
"compression_bytes_before": 0,
"compression_bytes_after": 0,
"compression_hit": 0,
"compression_miss": 0,
"compression_miss_no_client": 0,
"compression_miss_template_exclusion": 0,
"curr_req": 0,
"total_req": 0,
"total_req_succ": 0,
"peak_conn": 0,
"curr_conn_rate": 0,
"last_rsp_time": 0,
"fastest_rsp_time": 0,
"slowest_rsp_time": 0
},
"a10-url": "/axapi/v3/slb/virtual-server/vs1/port/80+http/stats",
"port-number": 80,
"protocol": "http"
}
}
Extended HTTP Statistics
The extended statistics for the slb virtual port are available with the addition of the http_vport=true filter:
curl -k GET https://10.10.10.10/axapi/v3/slb/virtual-server/vs1/port/80+http/stats?http_vport=true \
-H "Content-Type:application/json" \
-H "Authorization: A10 c223169c3ab18f9e3826b9df215c2b"
#Filtered Response
{
"port": {
"stats": {
"http_vport": {
"status_200": 0,
"status_201": 0,
"status_202": 0,
"status_203": 0,
"status_204": 0,
"status_205": 0,
"status_206": 0,
"status_207": 0,
"status_100": 0,
"status_101": 0,
"status_102": 0,
"status_103": 0,
"status_300": 0,
"status_301": 0,
"status_302": 0,
"status_303": 0,
"status_304": 0,
"status_305": 0,
"status_306": 0,
"status_307": 0,
"status_400": 0,
"status_401": 0,
"status_402": 0,
"status_403": 0,
"status_404": 0,
"status_405": 0,
"status_406": 0,
"status_407": 0,
"status_408": 0,
"status_409": 0,
"status_410": 0,
"status_411": 0,
"status_412": 0,
"status_413": 0,
"status_414": 0,
"status_415": 0,
"status_416": 0,
"status_417": 0,
"status_418": 0,
"status_422": 0,
"status_423": 0,
"status_424": 0,
"status_425": 0,
"status_426": 0,
"status_449": 0,
"status_450": 0,
"status_500": 0,
"status_501": 0,
"status_502": 0,
"status_503": 0,
"status_504": 0,
"status_504_ax": 0,
"status_505": 0,
"status_506": 0,
"status_507": 0,
"status_508": 0,
"status_509": 0,
"status_510": 0,
"status_1xx": 0,
"status_2xx": 0,
"status_3xx": 0,
"status_4xx": 0,
"status_5xx": 0,
"status_6xx": 0,
"status_unknown": 0,
"ws_handshake_request": 0,
"ws_handshake_success": 0,
"ws_client_switch": 0,
"ws_server_switch": 0,
"REQ_10u": 0,
"REQ_20u": 0,
"REQ_50u": 0,
"REQ_100u": 0,
"REQ_200u": 0,
"REQ_500u": 0,
"REQ_1m": 0,
"REQ_2m": 0,
"REQ_5m": 0,
"REQ_10m": 0,
"REQ_20m": 0,
"REQ_50m": 0,
"REQ_100m": 0,
"REQ_200m": 0,
"REQ_500m": 0,
"REQ_1s": 0,
"REQ_2s": 0,
"REQ_5s": 0,
"REQ_OVER_5s": 0
}
},
"a10-url": "/axapi/v3/slb/virtual-server/vs1/port/80+http/stats",
"port-number": 80,
"protocol": "http"
}
}
Note
The paging mechanism and field filtering mechanism cannot work with extended statistics filtering.
Reserved Filter Statistics
For typical config endpoints, there is a reserved ON/OFF filter called stats for getting config data and basic statistics data at the same time:
curl -k GET https://10.10.10.10/axapi/v3/slb/virtual-server/vs1/port/80+http?stats=true \
-H "Content-Type:application/json" \
-H "Authorization: A10 c223169c3ab18f9e3826b9df215c2b"
#Filtered Response
{
"port": {
"port-number": 80,
"protocol": "http",
"range": 0,
"conn-limit": 8000000,
"reset": 0,
"no-logging": 0,
"use-alternate-port": 0,
"action": "enable",
"def-selection-if-pref-failed": "def-selection-if-pref-failed",
"skip-rev-hash": 0,
"message-switching": 0,
"force-routing-mode": 0,
"reset-on-server-selection-fail": 0,
"clientip-sticky-nat": 0,
"extended-stats": 0,
"snat-on-vip": 0,
"stats-data-action": "stats-data-enable",
"syn-cookie": 0,
"no-auto-up-on-aflex": 0,
"no-dest-nat": 0,
"scaleout-bucket-count": 32,
"auto": 0,
"ipinip": 0,
"rtp-sip-call-id-match": 0,
"use-rcv-hop-for-resp": 0,
"redirect-to-https": 0,
"template-virtual-port": "default",
"uuid": "6e9cb4dc-3278-11df-a8af-000d480a65d0",
"stats": {
"curr_conn": 0,
"total_l4_conn": 0,
"total_l7_conn": 0,
"total_tcp_conn": 0,
"total_conn": 0,
"total_fwd_bytes": 0,
"total_fwd_pkts": 0,
"total_rev_bytes": 0,
"total_rev_pkts": 0,
"total_dns_pkts": 0,
"total_mf_dns_pkts": 0,
"es_total_failure_actions": 0,
"compression_bytes_before": 0,
"compression_bytes_after": 0,
"compression_hit": 0,
"compression_miss": 0,
"compression_miss_no_client": 0,
"compression_miss_template_exclusion": 0,
"curr_req": 0,
"total_req": 0,
"total_req_succ": 0,
"peak_conn": 0,
"curr_conn_rate": 0,
"last_rsp_time": 0,
"fastest_rsp_time": 0,
"slowest_rsp_time": 0
}
}
}
Note
This is not a /stats endpoint, but the addition of a ?stats=true filter. The extended statistics cannot work in this way.
Oper Endpoint Filtering¶
The oper endpoints end with the keyword /oper. These are used to retrieve dynamic operational status information from the back-end to see things like available memory, status of fans, admins logged in, etc. Filters are now also available for getting the status plus available extras such as total number of elements, a single record, and the configuration. The valid filters are defined by the oper field in the schema file. As the field filtering mechanism does, it accepts a string value. The paging mechanism is also supported. As of now, its scope is not the object instance. Instead, it works for oper fields within a multiple block.
Used by itself, the /oper endpoint will show operational data for each element within a collection or intermediate resource:
curl -k GET https://10.10.10.10/axapi/v3/admin-session/oper \
-H "Content-Type:application/json" \
-H "Authorization: A10 c223169c3ab18f9e3826b9df215c2b"
#Response
{
"admin-session": {
"oper" : {
"session-list": [
{
"sid":"1",
"name":"admin",
"src_ip":"10.10.10.11",
"type":"WEB",
"cfg_mode":"No"
},
{
"sid":"*3",
"name":"admin",
"src_ip":"10.10.10.12",
"type":"WEBSERVICE",
"cfg_mode":"No"
}
]
},
"a10-url":"/axapi/v3/admin-session/oper"
}
}
Used with the total paging mechanism, it will find the total number of elements at an endpoint. The back-end determines if oper field filtering mechanism works or not:
curl -k GET https://10.10.10.10/axapi/v3/admin-session/oper?total=true \
-H "Content-Type:application/json" \
-H "Authorization: A10 c223169c3ab18f9e3826b9df215c2b"
#Filtered Response
{
"total-count":2
}
In the following example, the start paging mechanism is used to find a single object instance record at an endpoint. The back-end determines if oper field filtering mechanism works or not:
curl -k GET https://10.10.10.10/axapi/v3/slb/server/s2/oper?start=0 \
-H "Content-Type:application/json" \
-H "Authorization: A10 c223169c3ab18f9e3826b9df215c2b"
#Filtered Response
{
"server": {
"oper": {
"state": "Down"
},
"a10-url": "/axapi/v3/slb/server/s2/oper",
"name": "s2"
}
}
For typical config endpoints, there is a reserved ON/OFF filter called oper for getting config data and basic operational data at the same time:
curl -k GET https://10.10.10.10/axapi/v3/slb/server/s1?oper=true \
-H "Content-Type:application/json" \
-H "Authorization: A10 c223169c3ab18f9e3826b9df215c2b"
#Filtered Response
{
"server": {
"name":"s1",
"host":"1.1.1.1",
"action":"disable",
"template-server":"default",
"health-check-disable":0,
"conn-limit":8000000,
"no-logging":0,
"weight":1,
"slow-start":0,
"spoofing-cache":0,
"stats-data-action":"stats-data-enable",
"extended-stats":0,
"uuid":"a25672e8-3270-11df-a8af-000d480a65d0",
"oper" : {
"state":"Disabled"
}
}
}
Note
This is not the /oper endpoint, but the addition of the ?oper=true filter.
Slot Filtering¶
The slot filters are used in chassis platforms to collect data from both Processing Units (PU) 1 and 2, as well as to aggregate statistical and basic operational data.
They are used to:
- Retrieve statistics and operational data from PU 1 and 2 individually
- Aggregate statistical data by default
- Aggregate operational data based on the schema with the metadata.
The ‘slot’ filter accepts an integer value that indicates the slot ID for PU1 or PU2. When ‘slot’ is set to 0, data is fetched from PU1. When ‘slot’ is set to 1, data is fetched from PU2. If ‘slot’ is not specified, the default slot ID is used. For statistical data, the default slot ID is 0 and 1. For operational data, the default slot ID is 0.
Some endpoints do not support processing units. For example:
GET /axapi/v3/ddos/dst/entry/oper?slot=1
{
"response": {
"status": "fail",
"err": {
"code": 1023655943,
"from": "JSON",
"msg": "Local only.",
"location": "slot"
}
}
}
The ‘slot’ filter can be specified multiple times to aggregate the specified PUs. For example:
GET /axapi/v3/system/control-cpu/stats?slot=0&slot=1
{
"control-cpu": {
"stats" : {
"ctrl-cpu-number":2,
"cpu-1":19,
"cpu-2":0,
}
}
}
Aggregating Statistics Data
By default, aXAPI automatically aggregates statistical data from all PUs. However, the ‘slot’ filter can be specified to fetch data on a per PU basis and retrieve information from a specific PU. For example:
GET /axapi/v3/system/control-cpu/stats?slot=0
{
"control-cpu": {
"stats" : {
"ctrl-cpu-number":1,
"cpu-1":15,
"cpu-2":0,
"cpu-3":0,
}
}
}
GET /axapi/v3/system/control-cpu/stats?slot=1
{
"control-cpu": {
"stats" : {
"ctrl-cpu-number":1,
"cpu-1":5,
"cpu-2":0,
}
}
}
GET /axapi/v3/system/control-cpu/stats
{
"control-cpu": {
"stats" : {
"ctrl-cpu-number":2,
"cpu-1":19,
"cpu-2":0,
}
}
}
Aggregating Operational Data
By default, aXAPI does not automatically aggregate the Operational data. It depends on the oper schema having corresponding attributes described by the metadata “slot-oper-merge,” “slot-num-add,” and “slot-aggregate” to perform the aggregation. Using these attributes can help aggregate the oper array list. For example, see the below request and its response. In response, each session-list entry has an additional field “slot_id” to indicate the PUs:
GET /axapi/v3/admin-session/oper
{
"admin-session": {
"oper" : {
"session-list": [
{
"sid":"2",
"name":"admin",
"start_time":"15:12:33 IST Fri May 20 2016",
"src_ip":"127.0.0.1",
"type":"WEBSERVICE",
"cfg_mode":"No",
"slot_id":0 [ PU1 slot id]
},
{
"sid":"*5",
"name":"admin",
"start_time":"15:34:55 IST Fri May 20 2016",
"src_ip":"172.17.65.23",
"type":"WEBSERVICE",
"cfg_mode":"No",
"slot_id":0
},
{
"sid":"2",
"name":"admin",
"start_time":"15:12:33 IST Fri May 20 2016",
"src_ip":"127.0.0.1",
"type":"WEBSERVICE",
"cfg_mode":"No",
"slot_id":1
},
{
"sid":"*5",
"name":"admin",
"start_time":"15:34:55 IST Fri May 20 2016",
"src_ip":"172.17.65.23",
"type":"WEBSERVICE",
"cfg_mode":"No",
"slot_id":1 [ PU2 slot id]
}
]
},
"a10-url":"/axapi/v3/admin-session/oper"
}
}
User Tag Filtering¶
The user tag filter is used by the GUI to group SSLi objects together by auto-configuring them with the Security string in the user-tag property. You can use these tags to filter your search results based on the string.
For example, when you create SSLi Services objects in the GUI for SSLi_vip_001, they will automatically be tagged with user-tag Security as seen in the show run command of the CLI:
!
slb server SSLi_vip_001_server_001 100.100.100.8
user-tag Security
port 0 tcp
...
!
slb service-group SSLi_vip_001_SSLi tcp
user-tag Security
member SSLi_vip_001_server_001 8080
...
!
slb template client-ssl SSLi_vip_001_client_ssl
user-tag Security
forward-proxy-bypass web-category health-and-medicine
...
!
slb virtual-server SSLi_vip_001 0.0.0.0 acl name acl_SSLi_vip_001
user-tag Security
port 0 tcp
...
!
end
In the case of searching by tag to retrieve all your SLB Security servers, you can use the user-tag=Security filter on your GET request. In the response, you will see the output of “user-tag”:”Security” in the SLB servers that were auto-configured with that property:
curl -k GET https://10.10.10.10/axapi/v3/slb/server?user-tag=Security \
-H "Content-Type:application/json" \
-H "Authorization: A10 c223169c3ab18f9e3826b9df215c2b"
#Filtered Response
{
"server-list": [
{
"name":"SSLi_vip_001_server_001",
"host":"100.100.100.8",
"action":"enable",
"template-server":"default",
"health-check-disable":0,
"conn-limit":8000000,
"no-logging":0,
"weight":1,
"slow-start":0,
"spoofing-cache":0,
"stats-data-action":"stats-data-enable",
"extended-stats":0,
"uuid":"f63899d6-c91e-11e5-ae81-fa163e0b5a56",
"user-tag":"Security",
"port-list": [
{
"port-number":0,
"protocol":"tcp",
"range":0,
"template-port":"default",
"action":"enable",
"no-ssl":0,
"health-check-disable":1,
"weight":1,
"conn-limit":8000000,
"no-logging":0,
"stats-data-action":"stats-data-enable",
"extended-stats":0,
"uuid":"f63aa1cc-c91e-11e5-ae81-fa163e0b5a56",
"a10-url":"/axapi/v3/slb/server/SSLi_vip_001_server_001/port/0+tcp"
},
{
"port-number":0,
"protocol":"udp",
"template-port":"default",
"action":"enable",
"no-ssl":0,
"health-check-disable":1,
"weight":1,
"conn-limit":8000000,
"no-logging":0,
"stats-data-action":"stats-data-enable",
"extended-stats":0,
"uuid":"f63be096-c91e-11e5-ae81-fa163e0b5a56",
"a10-url":"/axapi/v3/slb/server/SSLi_vip_001_server_001/port/0+udp"
},
{
"port-number":8080,
"protocol":"tcp",
"range":0,
"template-port":"default",
"action":"enable",
"no-ssl":0,
"health-check-disable":1,
"weight":1,
"conn-limit":8000000,
"no-logging":0,
"stats-data-action":"stats-data-enable",
"extended-stats":0,
"uuid":"f63be776-c91e-11e5-ae81-fa163e0b5a56",
"a10-url":"/axapi/v3/slb/server/SSLi_vip_001_server_001/port/8080+tcp"
}
],
"a10-url":"/axapi/v3/slb/server/SSLi_vip_001_server_001"
}
]
}