IControl® REST API User Guide Icontrol 13 0 C

User Manual:

Open the PDF directly: View PDF PDF.
Page Count: 142 [warning: Documents this large are best viewed by clicking the View PDF Link!]

iControl®REST API User Guide
Version 13.0
Table of Contents
REST............................................................................................................................................7
About Representational State Transfer..............................................................................7
Important changes in iControl REST API...........................................................................7
Overview: URI format and structure.................................................................................11
About reserved ASCII characters..........................................................................12
About REST resource identifiers...........................................................................13
About HTTP method semantics.......................................................................................13
About JSON request and response semantics................................................................14
About additional iControl REST properties...........................................................16
About null values and properties...........................................................................17
About reserved property names............................................................................18
About property name format differences...............................................................19
About JSON formats and encodings.....................................................................19
About API versions...........................................................................................................19
About iControl and authentication for user accounts ......................................................20
Requesting a token for iControl REST authentication...........................................20
Overview: Fundamentals of Cross-Origin Resource Sharing..........................................20
Cross-Origin Resource Sharing request headers.................................................21
Cross-Origin Resource Sharing response headers..............................................21
About external authentication providers with iControl REST...........................................22
GET Requests...........................................................................................................................25
Discovering modules and components ...........................................................................25
About paging properties........................................................................................27
About query parameters........................................................................................28
Paging through large collections...........................................................................29
About sub-collection expansion.............................................................................31
Returning resources from an administrative partition............................................34
Obtaining statistical output....................................................................................35
POST and PUT requests...........................................................................................................39
About JSON format for POST and PUT...........................................................................39
Creating a new resource with iControl.............................................................................39
Modifying a resource with PATCH.........................................................................40
About read only properties ...................................................................................41
Adding or modifying in a specific partition.............................................................42
Deleting Access Policy Manager resources..........................................................44
Partitions...................................................................................................................................45
3
Table of Contents
About administrative partitions.........................................................................................45
Creating folders.....................................................................................................45
Deleting an administrative partition.......................................................................47
Transactions..............................................................................................................................49
About the iControl REST transaction model....................................................................49
About iControl REST transaction phases..............................................................49
About transaction validation..................................................................................50
Creating an iControl REST transaction.................................................................50
Modifying a transaction.........................................................................................51
Committing an iControl REST transaction.............................................................52
About iControl REST asynchronous tasks.......................................................................53
Asynchronous task endpoints...............................................................................53
Using an asynchronous task.................................................................................54
Commands................................................................................................................................57
About other tmsh global commands.................................................................................57
Using the cp command..........................................................................................57
Using the generate command...............................................................................58
Using the install command....................................................................................58
Using the load command.......................................................................................59
Using the mv command.........................................................................................60
Using the publish command..................................................................................60
Using the reboot command...................................................................................60
Using the restart command...................................................................................61
Using the reset-stats command.............................................................................61
Using the run command........................................................................................62
Using the save command......................................................................................63
Using the send-mail command..............................................................................63
Using the start command......................................................................................64
Using the stop command.......................................................................................64
Application Security Manager.................................................................................................67
Application Security Manager and iControl REST comparison........................................67
Retrieving Application Security Manager resources..............................................69
Creating Application Security Manager resources................................................72
Updating Application Security Manager resources...............................................73
Deleting resources in Application Security Manager.............................................74
Application Security Manager policy.....................................................................74
Application Security Manager signatures..............................................................78
Application Security Manager schema upload......................................................83
Application Security Manager policy restore.........................................................83
Application Security Manager vulnerability import................................................85
Application Security Manager vulnerability resolution...........................................91
4
Table of Contents
Web Scraping Configuration settings....................................................................94
Learning Suggestion Object................................................................................101
About Device ID..................................................................................................105
About WebSockets..............................................................................................107
About AJAX/JSON Login.....................................................................................110
Access Policy Manager..........................................................................................................113
About Access Policy Manager ......................................................................................113
Overview: URI format and structure....................................................................113
About resource formats.......................................................................................114
About creating resources....................................................................................114
About retrieving resources..................................................................................114
About updating resources...................................................................................114
About deleting resources.....................................................................................115
HTTP Response Codes......................................................................................115
Retrieving Access Policy Manager resources................................................................115
Access Policy Manager endpoints.................................................................................118
Configuring LDAP settings in APM................................................................................119
Creating a custom category in APM..............................................................................121
Managing user sessions in APM....................................................................................123
API Life Cycle..........................................................................................................................125
REST API life cycle policy..............................................................................................125
Using the REST API life cycle changes.........................................................................125
Using the REST API life cycle changes with tmsh.........................................................128
Configuring the REST API life cycle settings.................................................................130
Configuring the REST API life cycle settings with tmsh.................................................131
Additional Features................................................................................................................133
About the example suffix................................................................................................133
About Access Policy Manager ......................................................................................133
About HTTP response codes.........................................................................................134
About log files................................................................................................................135
About public URIs..........................................................................................................136
Legal Notices..........................................................................................................................137
Legal notices..................................................................................................................137
5
Table of Contents
6
Table of Contents
REST
About Representational State Transfer
Representational State Transfer (REST) describes an architectural style of web services where clients and
servers exchange representations of resources. The REST model denes a resource as a source of information,
and also denes a representation as the data that describes the state of a resource. REST web services use
the HTTP protocol to communicate between a client and a server, specically by means of the POST, GET,
PUT, and DELETE methods, to create, read, update, and delete elements or collections. In general terms,
REST queries resources for the conguration objects of a BIG-IP®system, and creates, deletes, or modies
the representations of those conguration objects.
The iControl®REST implementation follows the REST model by:
• Using REST as a resource-based interface, and creating API methods based on nouns.
• Employing a stateless protocol and MIME data types, as well as taking advantage of the authentication
mechanisms and caching built into the HTTP protocol.
• Supporting the JSON format for document encoding.
• Representing the hierarchy of resources and collections with a Uniform Resource Identier (URI)
structure.
• Returning HTTP response codes to indicate success or failure of an operation.
• Including links in resource references to accommodate discovery.
Important changes in iControl REST API
This version of iControl®REST includes the changes described here that may impact existing iControl
REST scripts written for version 11.6. The changes are described as tmsh commands.
Changes in the BIG-IP DNS module:
configurationModule->cli_cmd->@{id:gtm-pool-member}->keyword->@{id:order}->$->id
Changed: <codeph>order</codeph> TO <codeph>member-order</codeph>
configurationModule->cli_cmd->@{id:gtm-pool}->keyword->@{id:max-address-returned}
Removed: "<keyword id="max-address-returned" attribute="answers_to_return"/>"
configurationModule->cli_cmd->@{id:gtm-pool}->keyword->@{id:canonical-name}
Removed: "<keyword id="canonical-name" attribute="cname"/>"
configurationModule->cli_cmd->@{id:gtm-pool}->keyword->@{id:fallback-ipv4}
Removed: "<keyword id="fallback-ipv4" attribute="fallback_ip"/>"
configurationModule->cli_cmd->@{id:gtm-pool}->keyword->@{id:fallback-ipv6}
Removed: "<keyword id="fallback-ipv6" attribute="fallback_ipv6"/>"
configurationModule->cli_cmd->@{id:gtm-pool}->keyword->@{id:monitor}
Removed: "<keyword id="monitor" attribute="monitor_rule" parser="gtm::pool-monitor-rule"/>"
configurationModule->cli_cmd->@{id:gtm-pool}->keyword->@{id:limit-max-bps}
Removed: "<keyword id="limit-max-bps" attribute="limits.bits_per_sec"/>"
configurationModule->cli_cmd->@{id:gtm-pool}->keyword->@{id:limit-max-bps-status}
Removed: "<keyword id="limit-max-bps-status" attribute="limits.bits_per_sec_enabled"
cli_enum="cli_enable_disable"/>"
configurationModule->cli_cmd->@{id:gtm-pool}->keyword->@{id:limit-max-pps}
Removed: "<keyword id="limit-max-pps" attribute="limits.pkts_per_sec"/>"
configurationModule->cli_cmd->@{id:gtm-pool}->keyword->@{id:limit-max-pps-status}
Removed: "<keyword id="limit-max-pps-status" attribute="limits.pkts_per_sec_enabled"
cli_enum="cli_enable_disable"/>"
configurationModule->cli_cmd->@{id:gtm-pool}->keyword->@{id:limit-max-connections}
Removed: "<keyword id="limit-max-connections" attribute="limits.connections"/>"
configurationModule->cli_cmd->@{id:gtm-pool}->keyword->@{id:limit-max-connections-status}
Removed: "<keyword id="limit-max-connections-status" attribute="limits.connections_enabled"
cli_enum="cli_enable_disable"/>"
configurationModule->cli_cmd->@{id:gtm-pool}->association->@{id:members}
Removed: "<association id="members" command="gtm-pool-member"> <attribute
set="gtm_pool_member.pool_name" from="gtm_pool.name"/> </association>"
configurationModule->cli_cmd->@{id:gtm-wideip}->keyword->@{id:ipv6-no-error-response}->$->id
Changed: "ipv6-no-error-response" TO "failure-rcode-response"
configurationModule->cli_cmd->@{id:gtm-wideip}->keyword->@{id:ipv6-no-error-neg-ttl}->$->id
Changed: "ipv6-no-error-neg-ttl" TO "failure-rcode-ttl"
configurationModule->cli_cmd->@{id:gtm-wideip}->keyword->@{id:last-resort-pool}
Removed: "<keyword id="last-resort-pool" attribute="last_resort_pool"/>"
configurationModule->cli_cmd->@{id:gtm-distributed-app}->association_list
Removed: "<association_list id="wideips" target="gtm_application_wideip.wip_name"> <attribute
set="gtm_application_wideip.application_name" from="gtm_application.name"/> </association_list>"
Changes in the LTM module:
configurationModule->cli_cmd->@{id:urldb_feed_list}->keyword->@{id:file}
Removed: "<keyword id="le" attribute="custom_urldb_le"/>"
configurationModule->cli_cmd->@{id:profile-diameter}->keyword->@{id:subscriber-aware}
Removed: "<keyword id="subscriber-aware" attribute="subscriber_aware"
cli_enum="cli_enable_disable"/>"
configurationModule->cli_cmd->@{id:profile-radius}->keyword->@{id:subscriber-aware}->$->id
Changed: "subscriber-aware" TO "subscriber-discovery"
configurationModule->cli_cmd->@{id:profile-radius}->keyword->@{id:subscriber-id-type}
Removed: "<keyword id="subscriber-id-type" attribute="subscriber_id_type"/>"
configurationModule->cli_cmd->@{id:profile-tcp}->keyword->@{id:nagle}->$->cli_enum
Removed: "cli_enable_disable"
configurationModule->cli_cmd->@{id:profile-classification}->keyword->@{id:description}
Removed: "<keyword id="description" attribute="description"/>"
8
REST
configurationModule->cli_cmd->@{id:profile-classification}->keyword->@{id:smtp-server}
Removed: "<keyword id="smtp-server" attribute="smtp_cong_name"/>"
configurationModule->cli_cmd->@{id:dns-tsig-key}->keyword->@{id:algorithm}
Removed: "<keyword id="algorithm" attribute="algorithm"
cli_enum="tmm_dns_tsig_key_algorithm_t"/>"
configurationModule->cli_cmd->@{id:dns-tsig-key}->keyword->@{id:secret}->$->id
Removed: "<keyword id="secret" attribute="secret"/>"
configurationModule->cli_cmd->@{id:dns-cache}->keyword->@{id:dnssec-on-miss}
Removed: "<keyword id="dnssec-on-miss" attribute="dnssec_on_miss" cli_enum="cli_yes_no"/>"
configurationModule->cli_cmd->@{id:dns-cache-resolver}->keyword->@{id:dnssec-on-miss}
Removed: "<keyword id="dnssec-on-miss" attribute="dnssec_on_miss" value="no"/>"
configurationModule->cli_cmd->@{id:dns-cache-resolver-validator}->keyword->@{id:dnssec-on-miss}
Removed: "<keyword id="dnssec-on-miss" attribute="dnssec_on_miss" value="no"/>"
Changes in the PEM module:
configurationModule->cli_cmd->@{id:pem-forwarding-endpoint}->keyword->@{id:persistence}->$->id
Changed: "persistence" TO "persistence.type"
configurationModule->cli_cmd->@{id:pem-globals__analytics}->keyword
Removed: "<keyword id="mode" attribute="avr_reporting_mode" cli_enum="cli_enable_disable"/>"
configurationModule->cli_cmd->@{id:pem-globals__analytics}->keyword
Removed: "<keyword id="logging.hsl.endpoint-id" attribute="hsl_endpoint_id"/>"
Changes in the APM module:
configurationModule->cli_cmd->@{id:agent-aaa-ocsp}->keyword
Removed: "<keyword id="ocsp-responder" attribute="ocsp_responder"/>"
Changes in the Security modules:
configurationModule->cli_cmd->@{id:fw-user-list}->keyword
Removed: "<keyword id="description" attribute="description"/>"
configurationModule->cli_cmd->@{id:fw-user-list}->association
Removed: "<association id="users" command="fw-user-list-entry" operations="add delete modify
replace-all-with"> <attribute set="fw_user_list_entry.list_name" from="fw_user_list.name"/>
</association>"
configurationModule->cli_cmd->@{id:fw-user-list}->association
Removed: "<association id="user-groups" command="fw-user-group-list-entry" operations="add delete
modify replace-all-with"> <attribute set="fw_user_group_list_entry.list_name"
from="fw_user_list.name"/> </association>"
configurationModule->cli_cmd->@{id:dos-application}->keyword->@{id:latency-based.mode}
Removed: "<keyword id="latency-based.mode" attribute="latency_based_mode"/>"
configurationModule->cli_cmd->@{id:dos-application}->keyword->@{id:behavior-based.mode}
Removed: "<keyword id="behavior-based.mode" attribute="behavior_based_mode"/>"
configurationModule->cli_cmd->@{id:dos-application}->keyword->@{id:latency-based.latency-increase-rate}
Removed: "<keyword id="latency-based.latency-increase-rate" attribute="latency_increase_rate"/>"
9
iControl®REST API User Guide
configurationModule->cli_cmd->@{id:dos-application}->keyword->@{id:latency-based.maximum-latency}
Removed: "<keyword id="latency-based.maximum-latency" attribute="maximum_latency"/>"
configurationModule->cli_cmd->@{id:dos-application}->keyword->@{id:latency-based.minimum-latency}
Removed: "<keyword id="latency-based.minimum-latency" attribute="minimum_latency"/>"
configurationModule->cli_cmd->@{id:dos-application}->keyword->@{id:latency-based.ip-client-side-defense}->$->id
Changed: "latency-based.ip-client-side-defense" TO "stress-based.ip-client-side-defense"
configurationModule->cli_cmd->@{id:dos-application}->keyword->@{id:latency-based.geo-client-side-defense}->$->id
Changed: "latency-based.geo-client-side-defense" TO "stress-based.geo-client-side-defense"
configurationModule->cli_cmd->@{id:dos-application}->keyword->@{id:latency-based.url-client-side-defense}->$->id
Changed: "latency-based.url-client-side-defense" TO "stress-based.url-client-side-defense"
configurationModule->cli_cmd->@{id:dos-application}->keyword->@{id:latency-based.site-client-side-defense}->$->id
Changed: "latency-based.site-client-side-defense" TO "stress-based.site-client-side-defense"
configurationModule->cli_cmd->@{id:dos-application}->keyword->@{id:latency-based.ip-captcha-challenge}->$->id
Changed: "latency-based.ip-captcha-challenge" TO "stress-based.ip-captcha-challenge"
configurationModule->cli_cmd->@{id:dos-application}->keyword->@{id:latency-based.geo-captcha-challenge}->$->id
Changed: "latency-based.geo-captcha-challenge" TO "stress-based.geo-captcha-challenge"
configurationModule->cli_cmd->@{id:dos-application}->keyword->@{id:latency-based.url-captcha-challenge}->$->id
Changed: "latency-based.url-captcha-challenge" TO "stress-based.url-captcha-challenge"
configurationModule->cli_cmd->@{id:dos-application}->keyword->@{id:latency-based.site-captcha-challenge}->$->id
Changed: "latency-based.site-captcha-challenge" TO "stress-based.site-captcha-challenge"
configurationModule->cli_cmd->@{id:dos-application}->keyword->@{id:latency-based.ip-rate-limiting}->$->id
Changed: "latency-based.ip-rate-limiting" TO "stress-based.ip-rate-limiting"
configurationModule->cli_cmd->@{id:dos-application}->keyword->@{id:latency-based.ip-request-blocking-mode}
Removed: "<keyword id="latency-based.ip-request-blocking-mode"
attribute="latency_based_source_ip_based_request_blocking_mode"/>"
configurationModule->cli_cmd->@{id:dos-application}->keyword->@{id:latency-based.geo-rate-limiting}->$->id
Changed: "latency-based.geo-rate-limiting" TO "stress-based.geo-rate-limiting"
configurationModule->cli_cmd->@{id:dos-application}->keyword->@{id:latency-based.geo-request-blocking-mode}
Removed: "<keyword id="latency-based.geo-request-blocking-mode"
attribute="latency_based_geolocation_based_request_blocking_mode"/>"
configurationModule->cli_cmd->@{id:dos-application}->keyword->@{id:latency-based.url-rate-limiting}->$->id
Changed: "latency-based.url-rate-limiting" TO "stress-based.url-rate-limiting"
configurationModule->cli_cmd->@{id:dos-application}->keyword->@{id:latency-based.site-rate-limiting}->$->id
Changed: "latency-based.site-rate-limiting" TO "stress-based.site-rate-limiting"
configurationModule->cli_cmd->@{id:dos-application}->keyword->@{id:latency-based.ip-tps-increase-rate}
Removed: "<keyword id="latency-based.ip-tps-increase-rate"
attribute="latency_based_ip_tps_increase_rate"/>"
configurationModule->cli_cmd->@{id:dos-application}->keyword->@{id:latency-based.ip-maximum-tps}
Removed: "<keyword id="latency-based.ip-maximum-tps"
attribute="latency_based_ip_maximum_tps"/>"
10
REST
configurationModule->cli_cmd->@{id:dos-application}->keyword->@{id:latency-based.ip-minimum-tps}
Removed: "<keyword id="latency-based.ip-minimum-tps" attribute="latency_based_ip_minimum_tps"/>"
configurationModule->cli_cmd->@{id:dos-application}->keyword->@{id:latency-based.geo-share-increase-rate}
Removed: "<keyword id="latency-based.geo-share-increase-rate"
attribute="latency_based_geolocation_trafc_share_increase_rate"/>"
configurationModule->cli_cmd->@{id:dos-application}->keyword->@{id:latency-based.geo-minimum-share}
Removed: "<keyword id="latency-based.geo-minimum-share"
attribute="latency_based_geolocation_trafc_minimum_share"/>"
configurationModule->cli_cmd->@{id:dos-application}->keyword->@{id:latency-based.url-tps-increase-rate}
Removed: "<keyword id="latency-based.url-tps-increase-rate"
attribute="latency_based_url_tps_increase_rate"/>"
configurationModule->cli_cmd->@{id:dos-application}->keyword->@{id:latency-based.url-maximum-tps}
Removed: "<keyword id="latency-based.url-maximum-tps"
attribute="latency_based_url_maximum_tps"/>"
configurationModule->cli_cmd->@{id:dos-application}->keyword->@{id:latency-based.url-minimum-tps}
Removed: "<keyword id="latency-based.url-minimum-tps"
attribute="latency_based_url_minimum_tps"/>"
configurationModule->cli_cmd->@{id:dos-application}->keyword->@{id:latency-based.site-tps-increase-rate}
Removed: "<keyword id="latency-based.site-tps-increase-rate"
attribute="latency_based_site_wide_tps_increase_rate"/>"
configurationModule->cli_cmd->@{id:dos-application}->keyword->@{id:latency-based.site-maximum-tps}
Removed: "<keyword id="latency-based.site-maximum-tps"
attribute="latency_based_site_wide_maximum_tps"/>"
configurationModule->cli_cmd->@{id:dos-application}->keyword->@{id:latency-based.site-minimum-tps}
Removed: "<keyword id="latency-based.site-minimum-tps"
attribute="latency_based_site_wide_minimum_tps"/>"
configurationModule->cli_cmd->@{id:dos-application}->keyword->@{id:latency-based.escalation-period}
Removed: "<keyword id="latency-based.escalation-period"
attribute="latency_based_escalation_period"/>"
configurationModule->cli_cmd->@{id:dos-application}->keyword->@{id:latency-based.de-escalation-period}
Removed: "<keyword id="latency-based.de-escalation-period"
attribute="latency_based_deescalation_period"/>"
configurationModule->cli_cmd->@{id:profile-httpsecurity}->keyword->@{id:methods.values}->$->tabc
Removed: "asm_http_method"
configurationModule->cli_cmd_mode->@{id:firewall-mode}->command->@{id:fw-user-group-entity}->$->keyword
Changed: "user-group-entity" TO "fqdn-entity"
Overview: URI format and structure
A principle of the REST architecture describes the identication of a resource by means of a Uniform
Resource Identier (URI). A URI identies the name of a web resource; in this case, the URI also represents
the tree structure of modules and components in tmsh. You can specify a URI with a web service request
to create, read, update, or delete some component or module of a BIG-IP®system conguration. In the
11
iControl®REST API User Guide
context of the REST architecture, the system conguration is synonymous with the representation of a
resource, and web service requests read and write that representation using the iControl®REST API.
Tip: Use admin, the default administrative account, for requests to iControl REST. Once you are familiar
with the API, you can create user accounts for iControl REST users with various permissions.
For the URI snippet shown here, the management-ip component of the URI is the fully qualied domain
name (FQDN) or IP address of a BIG-IP device.
https://<management-ip>/mgmt/tm/...
In iControl REST, the URI structure for all requests includes the string /mgmt/tm/ to identify the namespace
for trafc management. Any identiers that you append to that string specify collections.
https://<management-ip>/mgmt/tm/...
The ellipsis in the snippet indicates the location where you specify an organizing collection, which is a
collection of links to other resources in iControl REST. Organizing collections are the functional equivalent
of modules in tmsh. In other words, the organizing collection apm in iControl REST is the apm module. In
iControl REST, you can use the following URI to access all of the resources in the apm collection:
https://192.168.25.42/mgmt/tm/apm
Expanding on that approach, the URI in the following example designates all of the resources in the report
collection. You can think of a collection as the equivalent of a tmsh sub-module. An iControl REST
collection contains collections or resources.
https://192.168.25.42/mgmt/tm/apm/report
The URI in the following example designates a resource, which is a set of entities. In iControl REST, an
entity is a property that you can congure, such as "destAddrMax":2048. A resource may also contain
sub-collections. In the parlance of tmsh, a resource is the equivalent of a component.
https://192.168.25.42/mgmt/tm/apm/report/default-report
Important: iControl REST only supports secure access through HTTPS, so you must include credentials
with each REST call. Use the same credentials you use for the BIG-IP device manager interface.
About reserved ASCII characters
To accommodate the BIG-IP®conguration objects that use characters, which are not part of the unreserved
ASCII character set, use a percent sign (%) and two hexadecimal digits to represent them in a URI. The
unreserved character set consists of: [A - Z] [a - z] [0 - 9] dash (-), underscore (_),
period (.), and tilde(~)
You must encode any characters that are not part of the unreserved character set for inclusion in a URI
scheme. For example, an IP address in a non-default route domain that contains a percent sign to indicate
an address in a specic route domain, such as 192.168.25.90%3, should be encoded to replace the %
character with %25 .
12
REST
About REST resource identifiers
A URI is the representation of a resource that consists of a protocol, an address, and a path structure to
identify a resource and optional query parameters. Because the representation of folder and partition names
in tmsh often includes a forward slash (/), URI encoding of folder and partition names must use a different
character to represent a forward slash in iControl®REST. To accommodate the forward slash in a resource
name, iControl REST maps the forward slash to a tilde (~) character. When a resource name includes a
forward slash (/) in its name, substitute a tilde (~) for the forward slash in the path. For example, a resource
name, such as /Common/plist1, should be modied to the format shown here:
https://management-ip/mgmt/tm/security/firewall/port-list/~Common~plist1
About HTTP method semantics
Hypertext Transfer Protocol (HTTP 1.1) describes the methods and headers that build on the Uniform
Resource Identier (URI) that identies a collection or resource. The portion of a URI that makes up an
absolute path includes endpoints, such as /mgmt, that specify the path to a resource or collection. With the
exception of the X-F5-REST-Coordination-ID header that identies a transaction, iControl®REST does
not dene any additional HTTP headers. A collection is a set of resources of the same type, and a collection
is either a collection of resources or an organizing collection of links to resources. In the context of an HTTP
method, a URI identies a resource or collection as the target of a request.
In addition to the path of a resource, query parameters allow renement of the result set for a GET request.
A query string begins with a question mark (?) character and consists of expressions that rene the response
data. The iControl REST query parameters are implementations of the OData query parameters as well as
several custom query parameters. To distinguish the custom query parameters from OData query parameters,
iControl REST custom query parameters omit the dollar sign ($) as the rst character of the parameter.
The semantics of iControl REST methods behave differently depending on the URI. For a POST request,
a URI indicates a resource under which the request creates a subordinate resource. HTTP considers the
subordinate resource to be a new entity and not a modication of an existing entity. If the subordinate
resource already exists, the protocol considers a request to create the same resource as an error. For a PUT
request, a URI refers to an existing resource and the request modies the existing resource. For a PATCH
request, a URI refers to an existing resource and the request merges changes into the resource.
To address different requirements, iControl REST implements both PATCH and PUT methods. In iControl
REST, the PATCH method modies only the properties that you specify in a request. The PUT method
modies the properties that you specify in a request and sets the remaining properties to either default values
or empty values.
The semantics of iControl REST methods behave differently for collections and resources, as described in
the following table.
DescriptionMethod
For both collections and resources, iControl REST supports the GET method. Also
supports query strings.
GET
For both collections and resources, iControl REST supports the POST method.POST
For collections, iControl REST does not support the DELETE method. For resources,
iControl REST supports the DELETE method.
DELETE
For collections, iControl REST does not support the PUT method. For resources,
iControl REST supports the PUT method. For versions 11.6 and earlier, iControl
REST only partially supports the PUT method for resources.
PUT
13
iControl®REST API User Guide
DescriptionMethod
For collections, iControl REST does not support the PATCH method. For resources,
iControl REST supports the PATCH method.
PATCH
About JSON request and response semantics
When iControl REST processes a GET request, it generates a response code and a tJSONbody. Likewise,
an error response contains additional descriptive text in JSON format. To indicate the format of the text
body in a response, iControl REST sets the HTTP Content-Type header as application/json. A
response from iControl REST contains properties which describe a conguration object or the statistics for
a resource. In iControl REST, the term property refers to a name/value, or key/value, pair in a JSON object.
The JSON terminology consists of two structures: objects and arrays. An object is a collection of one or
more name/value pairs, as shown:
{ "partition":"Common" }
For a GET request, the properties consist of JSON objects or arrays, or both. Note that the name and value
appear in double quotes (" "), with a colon (:) separator between the name and the value. For objects that
contain multiple name pairs, additional name/value pairs are separated by a comma (,). An example of a
typical, albeit slightly dated, response from iControl REST illustrates the JSON body formatting.
{
"kind":"tm:ltm:ltmcollectionstate",
"selfLink":"https://localhost/mgmt/tm/ltm?ver=11.5.0",
"items":[
{
"reference":{
"link":"https://../mgmt/tm/ltm/auth?ver=11.5.0"
}
},
{
"reference":{
"link":"https://../mgmt/tm/ltm/classification?ver=11.5.0"
}
},
{
"reference":{
"link":"https://../mgmt/tm/ltm/data-group?ver=11.5.0"
}
},
{
"reference":{
"link":"https://../mgmt/tm/ltm/dns?ver=11.5.0"
}
},
{
"reference":{
"link":"https://../mgmt/tm/ltm/global-settings?ver=11.5.0"
}
},
{
"reference":{
"link":"https://../mgmt/tm/ltm/html-rule?ver=11.5.0"
}
},
{
"reference":{
14
REST
"link":"https://../mgmt/tm/ltm/message-routing?ver=11.5.0"
}
},
{
"reference":{
"link":"https://../mgmt/tm/ltm/monitor?ver=11.5.0"
}
},
{
"reference":{
"link":"https://../mgmt/tm/ltm/persistence?ver=11.5.0"
}
},
{
"reference":{
"link":"https://../mgmt/tm/ltm/profile?ver=11.5.0"
}
},
{
"reference":{
"link":"https://../mgmt/tm/ltm/default-node-monitor?ver=11.5.0"
}
},
{
"reference":{
"link":"https://../mgmt/tm/ltm/ifile?ver=11.5.0"
}
},
{
"reference":{
"link":"https://../mgmt/tm/ltm/lsn-pool?ver=11.5.0"
}
},
{
"reference":{
"link":"https://../mgmt/tm/ltm/nat?ver=11.5.0"
}
},
{
"reference":{
"link":"https://../mgmt/tm/ltm/node?ver=11.5.0"
}
},
{
"reference":{
"link":"https://../mgmt/tm/ltm/policy?ver=11.5.0"
}
},
{
"reference":{
"link":"https://../mgmt/tm/ltm/policy-strategy?ver=11.5.0"
}
},
{
"reference":{
"link":"https://../mgmt/tm/ltm/pool?ver=11.5.0"
}
},
{
"reference":{
"link":"https://../mgmt/tm/ltm/rule?ver=11.5.0"
}
},
{
"reference":{
"link":"https://../mgmt/tm/ltm/snat?ver=11.5.0"
}
},
{
15
iControl®REST API User Guide
"reference":{
"link":"https://../mgmt/tm/ltm/snat-translation?ver=11.5.0"
}
},
{
"reference":{
"link":"https://../mgmt/tm/ltm/snatpool?ver=11.5.0"
}
},
{
"reference":{
"link":"https://../mgmt/tm/ltm/traffic-class?ver=11.5.0"
}
},
{
"reference":{
"link":"https://../mgmt/tm/ltm/virtual?ver=11.5.0"
}
},
{
"reference":{
"link":"https://../mgmt/tm/ltm/virtual-address?ver=11.5.0"
}
}
]
}
About additional iControl REST properties
The iControl®REST implementation includes some document properties not present in Trafc Management
Shell (tmsh) output. The differences are noted in the table and appear in a response to a GET request of a
collection or resource, as shown in the example.
DescriptionPropertyName
A unique type identier.kind
A generation number for a resource. Modication of a resource, or a related
resource, changes the value. The value does not necessarily increase
generation
monotonically. For example, if you modify a resource in a sub-collection, the
modication may cause a change in the parent object.
A link to this resource.selfLink
{
"kind":"tm:sys:software:image:imagecollectionstate",
"selfLink":"https://localhost/mgmt/tm/sys/software/image?ver=11.5.0",
"items":[
{
"kind":"tm:sys:software:image:imagestate",
"name":"BIGIP-11.5.0.0.0.191.iso",
"fullPath":"BIGIP-11.5.0.0.0.191.iso",
"generation":38,
"selfLink":"https://../mgmt/tm/sys/software/image/BIGIP-11.5.0.0.0.191.iso?ver=11.5.0",
"build":"0.0.191",
"buildDate":"Wed Nov 27 14 03 09 PST 2013",
"checksum":"fab5b673486ccc1ec20fbe6cea51df50",
"fileSize":"1751 MB",
"lastModified":"Tue Dec 3 01:30:32 2013",
"product":"BIG-IP",
16
REST
"verified":"yes",
"version":"11.5.0"
},
{
"kind":"tm:sys:software:image:imagestate",
"name":"BIGIP-tmos-bugs-staging-11.5.0.0.0.237.iso",
"fullPath":"BIGIP-tmos-bugs-staging-11.5.0.0.0.237.iso",
"generation":37,
"selfLink":"https://../software/image/BIGIP-tmos-bugs-staging-11.5.0.0.0.237.iso?ver=11.5.0",
"build":"0.0.237",
"buildDate":"Wed Dec 4 14 14 44 PST 2013",
"checksum":"bb4ae4838a5743fa209f67a1b56dedef",
"fileSize":"1843 MB",
"lastModified":"Wed Dec 4 15:32:28 2013",
"product":"BIG-IP",
"verified":"yes",
"version":"11.5.0"
}
]
}
root@(BIG-IP1)(...)(tmos)# list sys software image
sys software image BIGIP-11.4.0.321.0.iso {
build 321.0
build-date "Mon Feb 11 07 23 24 PST 2013"
checksum f9411fde01d6a3521d4ae393e9bb077c
file-size "1522 MB"
last-modified "Mon Feb 11 09:35:50 2013"
product BIG-IP
verified yes
version 11.4.0
}
root@(BIG-IP1)(...)(tmos)#
About null values and properties
Flags are typically composed as a bit set by software to indicate state, such as 0or 1, and indicate on or off,
respectively. iControl®REST displays ags that are set with the ag name and a value of null. If the value
of a ag is none, iControl REST omits the property from the output.
Note: To POST or PUT a ag with only a single value, enter the property name in the JSON body with a
value of null.
{
"kind":"tm:sys:software:volume:volumecollectionstate",
"selfLink":"https://localhost/mgmt/tm/sys/software/volume?ver=11.5.0",
"items":[
{
"kind":"tm:sys:software:volume:volumestate",
"name":"MD1.1",
"fullPath":"MD1.1",
"generation":34,
"selfLink":"https://localhost/mgmt/tm/sys/software/volume/MD1.1?ver=11.5.0",
"basebuild":"0.0.191",
"build":"0.0.191",
"product":"BIG-IP",
"status":"complete",
17
iControl®REST API User Guide
"version":"11.5.0",
"media":[
{
"name":"MD1.1",
"media":"array",
"size":"default"
}
]
},
{
"kind":"tm:sys:software:volume:volumestate",
"name":"MD1.2",
"fullPath":"MD1.2",
"generation":35,
"selfLink":"https://localhost/mgmt/tm/sys/software/volume/MD1.2?ver=11.5.0",
"active":null,
"apiRawValues":{
},
"basebuild":"0.0.237",
"build":"0.0.237",
"product":"BIG-IP",
"status":"complete",
"version":"11.5.0",
"media":[
{
"name":"MD1.2",
"defaultBootLocation":null,
"media":"array",
"size":"default"
}
]
},
{
"kind":"tm:sys:software:volume:volumestate",
"name":"MD1.3",
"fullPath":"MD1.3",
"generation":36,
"selfLink":"https://localhost/mgmt/tm/sys/software/volume/MD1.3?ver=11.5.0",
"status":"complete",
"media":[
{
"name":"MD1.3",
"media":"array",
"size":"default"
}
]
}
]
}
About reserved property names
iControl®REST reserves several property names, most notably, the words name and generation. Some
tmsh components include properties with reserved property names. When iControl REST encounters a
reserved name in the JSON body, it replaces the reserved names with the corresponding replacement,
tmName or tmGeneration.
18
REST
About property name format differences
Property and option names in iControl®REST use a different naming convention than Trafc Management
(tmsh) Shell. In tmsh, property names consist of lowercase characters. For property names that contain
multiple words, hyphens separate the words. iControl REST uses camel case convention for property names,
where the rst word of a property is lowercase, and all additional words in the name are capitalized.
For example, the property build-date, as shown in tmsh, appears as buildDate in iControl REST.
About JSON formats and encodings
iControl®REST supports the following specications for string encodings:
• W3C XML Schema for numbers
• ISO 3166 for countries and territories
• ISO 6709 for latitude and longitude
• ISO for currency
• RFC 3339 for dates and times
• Olson Time Zone Database for time zones
• Time durations can be expressed as seconds since Unix Epoch (00:00:00 UTC on January 1, 1970), up
to one microsecond of fractional time.
For dates and times that are specic to a property in the conguration, a property name that incorporates
the time unit into the name, such as checkIntervalDays, provides a hint about the units of time.
About API versions
Over time, modications to the iControl®REST API may necessitate that a release is assigned a new version
number. To limit requests to a particular version of the API, iControl REST accepts an API version parameter
as an option to a URI. To use a particular API version, specify the ver parameter, an API version number,
such as 11.5.0, and append the string to the end of the URI, as you would with any query parameter.
GET https://192.168.25.42/mgmt/tm/ltm?ver=11.5.0
The JSON body for a response includes an API version number in the selfLink property, as well as any
links. For iControl REST, the version number of a resource in a response matches the version number sent
in a request. If you do not specify the version of the API, the version defaults to the current version. To
maintain backward compatibility with future releases of the API, a response will contain resources that
match the version number specied in the request. If iControl REST cannot generate a response that is
compatible with the request, it returns an error code.
Note: Although some REST implementations use HTTP headers to manage version information, iControl
REST does not use any HTTP headers to identify an API.
19
iControl®REST API User Guide
About iControl and authentication for user accounts
iControl®REST no longer requires that you grant permissions on iControl REST resources for individual
user accounts. As of version 12.0, a user automatically has access to REST resources, but the user must
acquire a token for authentication and include that token in all REST requests. Administrators of a BIG-IP®
system can still make REST requests by using basic authentication. Basic authentication requires a Base64
encoded string that consists of a user ID, a colon (:), and a password.
Requesting a token for iControl REST authentication
As an administrator of a BIG-IP®system, you can use basic authentication to make iControl®REST calls.
For users that lack administrator privileges, the user must request a token that can be used to authenticate
the user making REST API requests.
1. To create an authentication token, make a POST request to the BIG-IP®system. You must enclose both
the name and password values in double quotes (" "), as with any JSON string.
POST https://172.68.25.42/mgmt/shared/authn/login
{
"username": <user name>,
"password": <user password>,
"loginProviderName": "tmos"
}
The BIG-IQ®documentation species loginReference, which takes a reference to a login provider.
In the example, the loginProviderName property allows you to specify a name instead of a reference.
For most situations, use the loginProviderName and specify tmos.
2. To use the token in a REST request, copy the string for the token property and save it.
The token consists of a string of random letters and digits. In this example, the string is
492D3316E5456378B4AC9B5E2FA923595F0DA65A. The lifetime of the token is eight hours.
3. To make a REST request, add the token to request header. You must enclose the token within double
quotes (" "), as with any JSON string.
GET https://172.68.25.42/mgmt/tm/ltm
{ "X-F5-Auth-Token": "492D3316E5456378B4AC9B5E2FA923595F0DA65A" }
In this example, you acquired a token to include in an iControl REST request.
Overview: Fundamentals of Cross-Origin Resource Sharing
The same origin policy in browsers controls interactions between two different origins, such as requests
with XMLHttpRequest (XHR) objects. Furthermore, the same origin policy states that a browser that is
downloading data from a particular web site cannot interact with another resource that does not originate
from the same web site, where protocol, port number, and host name identify the web site. While there are
20
REST
mechanisms to implement a safe cross-site data transfer, Cross-Origin Resource Sharing (CORS) enables
secure cross-site data transfers by adding new HTTP headers to describe or enumerate a set of origins, as
well as to determine the viability of a request prior to the transmission of client data. The CORS headers
permit communication between a client and server to establish the limits of such requests.
CORS supports two types of requests: simple and preight. A simple request consists of a GET, HEAD,
or POST request. For POST requests, the Content-Type of the data sent to a server must be
application/x-www-form-urlencoded,multipart/form-data, or text/plain. One nal condition
for a simple request is that the request does not set custom headers.
For HTTP methods that modify a web resource, the CORS standard denes a preight capability that enables
a client to determine if a server allows a request. A client uses the preight mechanism if a request contains
a method other than GET, HEAD, or POST, or species a Content-Type header other than
application/x-www-form-urlencoded,multipart/form-data, or text/plain with a POST
request. Before the client sends a request with data, the client makes a request with the OPTIONS method
to query the server.
Finally, a client initiates a cross-origin request by including the Origin HTTP header in a request. A client
also includes the Access-Control-Request-Method and Access-Control-Request-Headers
headers in the cross-origin request. A server that allows a cross-origin request responds with an HTTP
Access-Control-Allow-Origin header and the value of the requesting origin, an
Access-Control-Request-Method header and supported methods, and an
Access-Control-Request-Headers header and supported values.
Cross-Origin Resource Sharing request headers
This table lists the request headers sent by a client, according to the Cross-Origin Resource Sharing (CORS)
specication.
DescriptionHTTP header
Species a URI that indicates the source of the
cross-origin or preight request.
Origin
Species the HTTP method that the client will send
in a request.
Access-Control-Request-Method
Species the HTTP headers that the client will
include in a request.
Access-Control-Request-Headers
Cross-Origin Resource Sharing response headers
This table lists the response headers sent by a server, in response to a preight request, according to the
Cross-Origin Resource Sharing (CORS) specication.
DescriptionHTTP header
Species a URI that is allowed to access a resource.
For iControl®REST users, this header lists origins
Access-Control-Allow-Origin
for which you allow requests. The iControl REST
implementation does not allow wild card characters
(*).
Species a list of HTTP headers that are safe to
expose. For iControl REST users, this header is a list
of F5®-specic headers that clients can access.
Access-Control-Expose-Headers
21
iControl®REST API User Guide
DescriptionHTTP header
Species the length of time to cache the results of a
preight request. The client should discard the results
Access-Control-Max-Age
after this time period expires. The value is either the
lesser of the session timeout value or one day.
Indicates whether to expose the response if the
credentials setting is true. For iControl REST users,
Access-Control-Allow-Credentials
this header indicates the allowance of authentication
cookies in a CORS request. Specify the value as
true. If you do not need cookies for authentication,
do not specify this header. You must also set the
withCredentials property of the
xmlHttpRequest object to true for a CORS
request to succeed.
Species only the methods for which the server
allows cross-origin access.
Access-Control-Allow-Methods
Species the headers that the server allows.Access-Control-Allow-Headers
About external authentication providers with iControl REST
iControl®REST supports external authentication to other providers, such as Active Directory (AD) or
RADIUS. Authentication with a provider other than the local authentication provider on a BIG-IP®system
requires a token that you can use to access resources in iControl REST. A token consists of 32 random
characters, primarily digits and uppercase ASCII characters, valid for a period of time. Until the token
expires, a server validates your identity based on the authentication token you submit. When the token
expires, you simply acquire a new token from a provider.
Note: Before you make a REST request using token-based authentication, you must obtain a token from
an external authentication provider.
You create a token by calling a user authentication method in the F5®REST API. Prior to making a token
creation request, you must obtain a login reference from your system administrator that identies an external
authentication provider. To create the authentication token, make a POST request and specify user name,
password, and login reference in the JSON body of the request. This request associates an authentication
token with a user name. If the token creation request is successful, the response contains a JSON body
similar to this.
{
"username":"auser",
"loginReference":{
"link":"https://localhost/mgmt/cm/system/authn/providers/ldap/298d4aa5-d255-438f-997d-7f984109dd5d/login"
},
"token":{
"uuid":"69c4b1c8-efdc-429a-b50c-723e92703a2b",
"name":"492D3316E5456378B4AC9B5E2FA923595F0DA65A",
"token":"492D3316E5456378B4AC9B5E2FA923595F0DA65A",
"userName":"USERNAME",
"user":{
"link":"https://localhost/mgmt/cm/system/authn/providers/ldap/298d4aa5-d255-438f997d7f984109dd5d/users/a25e2147-92e0-4349-ac99-7c844b3d30c2"
22
REST
},
"groupReferences":[
],
"timeout":1200,
"startTime":"2014-07-08T17:14:34.305-0700",
"address":"192.168.2.2",
"partition":"[All]",
"generation":1,
"lastUpdateMicros":1404864874295548,
"expirationMicros":1404866074305000,
"kind":"shared:authz:tokens:authtokenitemstate",
"selfLink":"https://localhost/mgmt/shared/authz/tokens/69c4b1c8-efdc-429a-b50c-723e92703a2b"
},
"generation":0,
"lastUpdateMicros":0
}
The token property identies the value to include in a request. In the JSON body, the token is the string
492D3316E5456378B4AC9B5E2FA923595F0DA65A, inside of the token object. To be authenticated by
the resource, you must include the X-F5-Auth-Token header in a REST request and specify the token
value in the header. If you prefer to authenticate locally, you can leave the Authorization header blank.
For more information about obtaining and using an authentication token, see BIG-IQ®Systems: REST API
Reference.
23
iControl®REST API User Guide
GET Requests
Discovering modules and components
iControl®REST supports discovery through a GET request. The structure of resources becomes more
obvious as you investigate the organizing collections. One other benet of discovering the organizing
collections is the relationship between iControl REST and tmsh.
To discover the structure, make a request to iControl REST with the GET method and specify an
organizing collection, as shown in this example.
GET https://192.168.25.42/mgmt/tm/ltm
{
"items":[
{
"reference":{
"link":"https://localhost/mgmt/tm/ltm/auth?ver=11.5.0"
}
},
{
"reference":{
"link":"https://../mgmt/tm/ltm/classification?ver=11.5.0"
}
},
{
"reference":{
"link":"https://../mgmt/tm/ltm/data-group?ver=11.5.0"
}
},
{
"reference":{
"link":"https://localhost/mgmt/tm/ltm/dns?ver=11.5.0"
}
},
{
"reference":{
"link":"https://../mgmt/tm/ltm/global-settings?ver=11.5.0"
}
},
{
"reference":{
"link":"https://../mgmt/tm/ltm/html-rule?ver=11.5.0"
}
},
{
"reference":{
"link":"https://../mgmt/tm/ltm/message-routing?ver=11.5.0"
}
},
{
"reference":{
"link":"https://../mgmt/tm/ltm/monitor?ver=11.5.0"
}
},
{
"reference":{
"link":"https://../mgmt/tm/ltm/persistence?ver=11.5.0"
}
},
{
"reference":{
"link":"https://../mgmt/tm/ltm/profile?ver=11.5.0"
}
},
{
"reference":{
"link":"https://../mgmt/tm/ltm/default-node-monitor?ver=11.5.0"
}
},
{
"reference":{
"link":"https://../mgmt/tm/ltm/ifile?ver=11.5.0"
}
},
{
"reference":{
"link":"https://../mgmt/tm/ltm/lsn-pool?ver=11.5.0"
}
},
{
"reference":{
"link":"https://../mgmt/tm/ltm/nat?ver=11.5.0"
}
},
{
"reference":{
"link":"https://../mgmt/tm/ltm/node?ver=11.5.0"
}
},
{
"reference":{
"link":"https://../mgmt/tm/ltm/policy?ver=11.5.0"
}
},
{
"reference":{
"link":"https://../mgmt/tm/ltm/policy-strategy?ver=11.5.0"
}
},
{
"reference":{
"link":"https://../mgmt/tm/ltm/pool?ver=11.5.0"
}
},
{
"reference":{
"link":"https://../mgmt/tm/ltm/rule?ver=11.5.0"
}
},
{
"reference":{
"link":"https://../mgmt/tm/ltm/snat?ver=11.5.0"
}
},
{
"reference":{
"link":"https://../mgmt/tm/ltm/snat-translation?ver=11.5.0"
}
},
{
"reference":{
"link":"https://../mgmt/tm/ltm/snatpool?ver=11.5.0"
}
26
GET Requests
},
{
"reference":{
"link":"https://../mgmt/tm/ltm/traffic-class?ver=11.5.0"
}
},
{
"reference":{
"link":"https://../mgmt/tm/ltm/virtual?ver=11.5.0"
}
},
{
"reference":{
"link":"https://../mgmt/tm/ltm/virtual-address?ver=11.5.0"
}
}
],
"kind":"tm:ltm:ltmcollectionstate",
"selfLink":"https://localhost/mgmt/tm/ltm?ver=11.5.0"
}
If you are familiar with command-line tools, use curl, or a similar utility, to make a request to iControl
REST. In the URI, specify an organizing collection. For example, the command: curl -k -u
admin:admin -X GET https://192.168.25.42/mgmt/tm/ltm makes a request of the ltm
organizing collection.
Note: The contents of an iControl REST resource may not have all of the properties and options of its tmsh
counterpart below the sub-collection level.
Note: A module that is not provisioned on a BIG-IP®system will not appear in the output.
Note:
About paging properties
iControl®REST supports pagination options for large collections. The implementation of pagination utilizes
the Open Data Protocol (OData) query parameters to provide information that you can use to navigate a
large result set. When you request a large collection, the iControl REST response includes properties to
identify the URI for the collection, the next page of the result set, the previous page of the result set, as well
as the total number of items in the result, total number of pages, the current page, the number of items per
page, and a count of the number of items in the current page. iControl®REST calculates these values on
the ltered result set.
27
iControl®REST API User Guide
DescriptionProperty
The URI of the collection, including any query parameters.selfLink
The next set of data in the result set. Includes the $skip query parameter
in the link.
nextLink
The previous set of data in the result set. Not present in the rst set of data.previousLink
A count of the number of items in the result set, either as the value of the
$top query parameter, or the remaining number of items if less than the
number requested.
currentItemCount
The number of items to display per page.itemsPerPage
The current page in the result set.pageIndex
The total number of pages in the result set, equal to the result of (totalItems
/ itemsPerPage), rounded up to the next integer value.
totalPages
The index of the rst item in the result set.startIndex
The number of items in the result set, as calculated by the
$inlinecount=allpages query parameter.
totalItems
About query parameters
iControl®REST implements a subset of the Open Data Protocol (OData) recommendations for query
languages and system query options. The OData protocol denes System Query Options that are query
string parameters to manage the presentation of data in a result set identied by a URL. For example, you
can include or exclude rows from a result set, constrain a query to resources contained within an administrative
partition, or specify a particular version of iControl REST. With the exception of the asm module, query
parameters are limited to GET requests.
To use a query parameter, append a query parameter expression to the end of a request URI. All query
parameter expressions begin with a question mark (?), followed by a query parameter name, a comparison
or logical operator, and a value. A value adheres to the camel case naming convention for iControl REST.
OData query parameters begin with a dollar sign ($), whereas custom query parameters do not. For example,
you can specify that the response only include the name property in the following request:
GET https://localhost/mgmt/tm/ltm/pool/?$select=name
To specify additional query parameters, precede each additional query parameter with an ampersand (&),
then specify the query parameter expression. The following table lists the parameters that are iControl REST
implementations of the OData query parameters. All OData query parameters begin with a dollar sign ($).
Note that the $filter parameter, if used, limits the result set to a specic administrative partition.
DescriptionParameter
Species an administrative partition to query for a result set. This parameter lters
the result set by partition name and does not fully implement the corresponding
$filter
OData query parameter. The asm module fully implements the OData query
parameter.
Species a subset of the properties that will appear in the result set.$select
Species the number of rows to skip in the result set. The result set is chosen from
the remaining rows.
$skip
Species the rst N rows of the result set.$top
28
GET Requests
iControl REST supports comparison and logical operators as described in the OData recommendation.
DescriptionOperator
Equal toeq
Not equal tone
Less thanlt
Less than or equal tole
Greater thangt
Greater than or equal toge
True if both operands are trueand
True if either operand is trueor
Negation of operandnot
Note: iControl REST supports only the eq operator with the $lter parameter.
iControl REST includes several custom query parameters. The custom query parameters do not include a
dollar sign ($) character in the parameter name.
DescriptionParameter
Species that iControl REST expand any references to sub collections when
set to true. By default, the response to a GET request only contains links for
sub collection reference properties.
expandSubcollections
Species the options to a query request. This parameter takes values that are
compatible with the tmsh command-line options.
options
Species the version number of the iControl®REST API to use when making
a request. Defaults to the current version if you do not specify a value.
ver
Paging through large collections
Collections that contain a large number of items consume a great deal of network bandwidth and processing
power if processed in a single GET request. Query parameters allow you to manage multi page responses.
iControl®REST supports the OData system query parameters $top and $skip to return pages items sets.
Use the $top query parameter to specify the maximum number of items for the BIG-IP®device to return.
If you use curl and run this command from a Unix command line, precede the dollar sign character ($)
with a backslash character (\) to prevent shell interpretation of the character.
curl -k -u admin:admin -X GET https://192.168.25.42/mgmt/tm/sys?\$top=4
29
iControl®REST API User Guide
To query for the rst ndata items, specify the URI, and append the $top query parameter to the URI. This
query displays the rst four items in the sys collection output. The response indicates the nextLink and
previousLink properties that serve as navigation markers to the next page and previous page, respectively.
https://192.168.25.42/mgmt/tm/sys?$top=4
{ "currentItemCount" : 4,
"items" : [
{ "reference" :
{ "link" : "https://../mgmt/tm/sys/application?ver=11.5.0" } }
{ "reference" :
{ "link" : "https://../mgmt/tm/sys/crypto?ver=11.5.0" } }
{ "reference" :
{ "link" : "https://../mgmt/tm/sys/daemon-log-settings?ver=11.5.0" }
}
{ "reference" :
{ "link" : "https://../mgmt/tm/sys/disk?ver=11.5.0" } }
],
"itemsPerPage" : 4,
"kind" : "tm:sys:syscollectionstate",
"nextLink" : "https://localhost/mgmt/tm/sys?$top=4&$skip=4&ver=11.5.0",
"pageIndex" : 1,
"selfLink" : "https://localhost/mgmt/tm/sys?$top=4&ver=11.5.0",
"startIndex" : 1,
"totalItems" : 36,
"totalPages" : 9
}
To request the next ndata items, use the same URI as the previous example and append the $skip query
parameter to the URI. This example displays the next four items in the sys collection output. The response
also indicates the nextLink and previousLink properties that serve as navigation markers into the data.
https://192.168.25.42/mgmt/tm/sys?$top=4&$skip=4
{ "currentItemCount" : 4,
"items" : [
{ "reference" :
{ "link" : "https://../mgmt/tm/sys/file?ver=11.5.0" } },
{ "reference" :
{ "link" : "https://../mgmt/tm/sys/icall?ver=11.5.0" } },
{ "reference" :
{ "link" : "https://../mgmt/tm/sys/log-config?ver=11.5.0" } },
{ "reference" :
{ "link" : "https://../mgmt/tm/sys/sflow?ver=11.5.0" } }
],
"itemsPerPage" : 4,
"kind" : "tm:sys:syscollectionstate",
"nextLink" : "https://localhost/mgmt/tm/sys?$top=4&$skip=8&ver=11.5.0",
"pageIndex" : 2,
"previousLink" : "https://localhost/mgmt/tm/sys?$top=4&ver=11.5.0",
"selfLink" : "https://localhost/mgmt/tm/sys?$top=4&$skip=4&ver=11.5.0",
"startIndex" : 5,
"totalItems" : 36,
"totalPages" : 9
}
30
GET Requests
About sub-collection expansion
iControl®REST supports the expandSubcollections query parameter. In tmsh, conguration components
contain properties, child components, and associated, non-child components. For example, you can create
an associated component independently from the component that contains it,such as a virtual server (the
ltm virtual component in tmsh) that contains an LTM®pool, even though you create the LTM pool as
a separate task.
If set to true, the expandSubcollections query parameter displays all child components but omits any
associated non-child components from the response.
Although the command creates a lengthy output block, the query parameter displays the properties of the
sub-collection, in addition to the properties of the component. As with other query parameters, the
expandSubcollections parameter does not support requests other than a GET request.
https://192.168.25.42/mgmt/tm/ltm/virtual/my-VS/?expandSubcollections=true
{
"kind":"tm:ltm:virtual:virtualstate",
"name":"my-VS",
"fullPath":"my-VS",
"generation":1,
"selfLink":"https://../tm/ltm/virtual/my-VS?expandSubcollections=true&ver=11.5.0",
"autoLasthop":"default",
"cmpEnabled":"yes",
"connectionLimit":0,
"destination":"/Common/10.2.1.189:0",
"enabled":null,
"gtmScore":0,
"ipProtocol":"tcp",
"mask":"255.255.255.255",
"mirror":"disabled",
"mobileAppTunnel":"disabled",
"nat64":"disabled",
"pool":"/Common/my-Pool",
"rateLimit":"disabled",
"rateLimitDstMask":0,
"rateLimitMode":"object",
"rateLimitSrcMask":0,
"source":"0.0.0.0/0",
"sourceAddressTranslation":{
"type":"automap"
},
"sourcePort":"preserve",
"synCookieStatus":"not-activated",
"translateAddress":"enabled",
"translatePort":"disabled",
"vlansDisabled":null,
"vsIndex":2,
"policiesReference":{
"link":"https://../tm/ltm/virtual/~Common~my-VS/policies?ver=11.5.0",
"isSubcollection":true,
"items":[
{
"kind":"tm:ltm:virtual:policies:policiesstate",
"name":"asm_auto_l7_policy__my-VS",
"partition":"Common",
"fullPath":"/Common/asm_auto_l7_policy__my-VS",
"generation":1,
31
iControl®REST API User Guide
"selfLink":"https://../~Common~my-VS/policies/~Common~asm_auto_l7_policy__my-VS?ver=11.5.0"
}
]
},
"securityLogProfiles":[
"\"/Common/Log illegal requests\""
],
"fwRulesReference":{
"link":"https://../tm/ltm/virtual/~Common~my-VS/fw-rules?ver=11.5.0",
"isSubcollection":true
},
"profilesReference":{
"link":"https://../tm/ltm/virtual/~Common~my-VS/profiles?ver=11.5.0",
"isSubcollection":true,
"items":[
{
"kind":"tm:ltm:virtual:profiles:profilesstate",
"name":"http",
"partition":"Common",
"fullPath":"/Common/http",
"generation":1,
"selfLink":"https://../tm/ltm/virtual/~Common~my-VS/profiles/~Common~http?ver=11.5.0",
"context":"all"
},
{
"kind":"tm:ltm:virtual:profiles:profilesstate",
"name":"tcp",
"partition":"Common",
"fullPath":"/Common/tcp",
"generation":1,
"selfLink":"https://../tm/ltm/virtual/~Common~my-VS/profiles/~Common~tcp?ver=11.5.0",
"context":"all"
},
{
"kind":"tm:ltm:virtual:profiles:profilesstate",
"name":"websecurity",
"partition":"Common",
"fullPath":"/Common/websecurity",
"generation":1,
"selfLink":"https://../tm/ltm/virtual/~Common~my-VS/profiles/~Common~websecurity?ver=11.5.0",
"context":"all"
}
]
}
}
Expanding a sub-collection reference
The responses from iControl®REST can include references to sub collections. The expandSubcollections
query parameter expands references to sub-collections.
View the details of a particular resource, including the details of its sub-collections, append the string
expandSubcollections=true to the URI. Do not prepend a dollar sign ($) to this query parameter.
32
GET Requests
To see the differences, this example shows a GET request for a resource with sub-collection expansion.
The response contains the isSubcollection property, set to true, to indicate a sub-collection. The output
only contains a reference to the sub-collection.
https://192.168.42.25/mgmt/tm/ltm/pool/~Common~my-Pool
{ "allowNat" : "yes",
"allowSnat" : "yes",
"description" : "sdfds",
"fullPath" : "/Common/my-Pool",
"generation" : 1,
"ignorePersistedWeight" : "disabled",
"ipTosToClient" : "pass-through",
"ipTosToServer" : "pass-through",
"kind" : "tm:ltm:pool:poolstate",
"linkQosToClient" : "pass-through",
"linkQosToServer" : "pass-through",
"loadBalancingMode" : "round-robin",
"membersReference" : { "isSubcollection" : true,
"link" : "https://../mgmt/tm/ltm/pool/~Common~my-Pool/members?ver=11.5.0"
},
"minActiveMembers" : 0,
"minUpMembers" : 0,
"minUpMembersAction" : "failover",
"minUpMembersChecking" : "disabled",
"name" : "my-Pool",
"partition" : "Common",
"queueDepthLimit" : 0,
"queueOnConnectionLimit" : "disabled",
"queueTimeLimit" : 0,
"reselectTries" : 0,
"selfLink" : "https://../mgmt/tm/ltm/pool/~Common~my-Pool?ver=11.5.0",
"slowRampTime" : 10
}
To see the expanded sub-collection, this example uses the expandSubcollections query parameter.
iControl®REST supports the custom expandSubcollections query parameter, which omits the dollar
sign ($) from its name.
https://192.168.25.42/mgmt/tm/ltm/pool/~Common~my-Pool/?expandSubcollections=true
{ "allowNat" : "yes",
"allowSnat" : "yes",
"description" : "sdfds",
"fullPath" : "/Common/my-Pool",
"generation" : 1,
"ignorePersistedWeight" : "disabled",
"ipTosToClient" : "pass-through",
"ipTosToServer" : "pass-through",
"kind" : "tm:ltm:pool:poolstate",
"linkQosToClient" : "pass-through",
"linkQosToServer" : "pass-through",
"loadBalancingMode" : "round-robin",
"membersReference" : { "isSubcollection" : true,
"items" : [ { "address" : "1.1.1.1",
"connectionLimit" : 0,
"dynamicRatio" : 1,
"fullPath" : "/Common/block:0",
"generation" : 1,
33
iControl®REST API User Guide
"inheritProfile" : "enabled",
"kind" : "tm:ltm:pool:members:membersstate",
"logging" : "disabled",
"monitor" : "default",
"name" : "block:0",
"partition" : "Common",
"priorityGroup" : 0,
"rateLimit" : "disabled",
"ratio" : 1,
"selfLink" :
"https://../tm/ltm/pool/~Common~my-Pool/members/~Common~block:0?ver=11.5.0",
"session" : "user-enabled",
"state" : "unchecked"
} ],
"link" : "https://../tm/ltm/pool/~Common~my-Pool/members?ver=11.5.0"
},
"minActiveMembers" : 0,
"minUpMembers" : 0,
"minUpMembersAction" : "failover",
"minUpMembersChecking" : "disabled",
"name" : "my-Pool",
"partition" : "Common",
"queueDepthLimit" : 0,
"queueOnConnectionLimit" : "disabled",
"queueTimeLimit" : 0,
"reselectTries" : 0,
"selfLink" :
"https://../tm/ltm/pool/~Common~my-Pool?expandSubcollections=true&ver=11.5.0",
"slowRampTime" : 10
}
Returning resources from an administrative partition
To access an administrative partition, use the $filter query parameter in a GET request to specify a
resource in a partition.
1. Access a partition other than Common, using the $filter query option at the end of the URI.
2. Encode the URI by creating the following string: ?$filter=partition%20eq%20fw_objs
To use a lter parameter, this example shows a GET request that uses a lter setting to limit the query to a
specic partition. The response from the request appears in the second block.
GET https://192.168.25.42/mgmt/tm/ltm/pool/?$filter=partition eq fw_objs
{
"kind":"tm:ltm:pool:poolcollectionstate",
"selfLink":"https://../mgmt/tm/ltm/pool?$filter=partition%20eq%20fw_objs&ver=11.5.0",
"items":[
{
"kind":"tm:ltm:pool:poolstate",
"name":"tcb-pool2",
"partition":"fw_objs",
"fullPath":"/fw_objs/tcb-pool2",
"generation":9587,
34
GET Requests
"selfLink":"https://../mgmt/tm/ltm/pool/~fw_objs~tcb-pool2?ver=11.5.0",
"allowNat":"yes",
"allowSnat":"yes",
"description":"This pool exists in the fw_objs partition.",
"ignorePersistedWeight":"disabled",
"ipTosToClient":"pass-through",
"ipTosToServer":"pass-through",
"linkQosToClient":"pass-through",
"linkQosToServer":"pass-through",
"loadBalancingMode":"round-robin",
"minActiveMembers":0,
"minUpMembers":0,
"minUpMembersAction":"failover",
"minUpMembersChecking":"disabled",
"queueDepthLimit":0,
"queueOnConnectionLimit":"disabled",
"queueTimeLimit":0,
"reselectTries":0,
"slowRampTime":10,
"membersReference":{
"link":"https://../mgmt/tm/ltm/pool/~fw_objs~tcb-pool2/members?ver=11.5.0",
"isSubcollection":true
}
}
]
}
Obtaining statistical output
The response to a GET request contains the JSON representations that are equivalent to the output of the
tmsh list command. iControl®REST includes a sufx for statistical information that produces statistical
output equivalent to the tmsh show command.
1. Obtain statistical results for a resource by specifyi the resource of interest in the URI.
2. Append the endpoint stats to the URI of the resource to obtain statistical output.
To obtain statistics for a resource, this example queries the /Common/my-Pool object for current statistics.
The response that contains the statistical output appears in the second block.
GET https://192.168.25.42/mgmt/tm/ltm/pool/~Common~my-Pool/stats
{
"kind":"tm:ltm:pool:poolstats",
"generation":1,
"selfLink":"https://../mgmt/tm/ltm/pool/~Common~my-Pool/stats?ver=11.5.0",
"entries":{
"activeMemberCnt":{
"value":0
},
"connqAll.ageEdm":{
"value":0
},
"connqAll.ageEma":{
35
iControl®REST API User Guide
"value":0
},
"connqAll.ageHead":{
"value":0
},
"connqAll.ageMax":{
"value":0
},
"connqAll.depth":{
"value":0
},
"connqAll.serviced":{
"value":0
},
"connq.ageEdm":{
"value":0
},
"connq.ageEma":{
"value":0
},
"connq.ageHead":{
"value":0
},
"connq.ageMax":{
"value":0
},
"connq.depth":{
"value":0
},
"connq.serviced":{
"value":0
},
"curSessions":{
"value":0
},
"minActiveMembers":{
"value":0
},
"monitorRule":{
"description":"none"
},
"tmName":{
"description":"/Common/my-Pool"
},
"serverside.bitsIn":{
"value":0
},
"serverside.bitsOut":{
"value":0
},
"serverside.curConns":{
"value":0
},
"serverside.maxConns":{
"value":0
},
"serverside.pktsIn":{
"value":0
},
"serverside.pktsOut":{
"value":0
},
"serverside.totConns":{
"value":0
},
"status.availabilityState":{
"description":"unknown"
},
36
GET Requests
"status.enabledState":{
"description":"enabled"
},
"status.statusReason":{
"description":"The children pool member(s) either don't have service
checking enabled, or service check results are not available yet"
},
"totRequests":{
"value":0
}
}
}
For comparison, this is the response from the tmsh command to display statistical output.
root@(BIG-IP1)(...)(tmos)# show ltm pool my-Pool
---------------------------------------------------------------------
Ltm::Pool: my-Pool
---------------------------------------------------------------------
Status
Availability : unknown
State : enabled
Reason : The children pool member(s) either don't have service checking
enabled, or service check results are not available yet
Monitor : none
Minimum Active Members : 0
Current Active Members : 0
Total Requests : 0
Current Sessions : 0
Traffic ServerSide
Bits In 0
Bits Out 0
Packets In 0
Packets Out 0
Current Connections 0
Maximum Connections 0
Total Connections 0
Connection Queue Pool Pool and members
Number of connections queued now 0 0
Number of connections serviced 0 0
Queue head entry age (ms) 0 0
Maximum queue entry age ever (ms) 0 0
Maximum queue entry age recently (ms) 0 0
Average queue entry age (ms) 0 0
root@(BIG-IP1)(...)(tmos)#
37
iControl®REST API User Guide
POST and PUT requests
About JSON format for POST and PUT
Unlike a GET request, a POST or PUT request includes a JSON body. When you create or modify a resource,
you use the same JavaScript Object Notation (JSON) format as shown in a GET request to dene the
conguration of an object. Use POST to create a new conguration object from a JSON body, and use PUT
or PATCH to edit an existing conguration object with a JSON body.
The format of the JSON body consists of objects that follow the model for an object, as shown:
{ "partition":"Common" }
Both the name and value appear in double quotes, and a colon separates the name and the value in the pair.
For objects that contain multiple name pairs, a comma ( , ) separates additional name/value pairs. A JSON
value must be an object, array, number, string, or one of three literal names: false,null, or true. The
other structure is a JSON array, or collection, which is an ordered list of values, as shown:
[ { "components":8, "isSubcomponent":"true" } ]
In JSON format, square brackets enclose the objects in an array. The objects in the array follow the JSON
standard for name/value pairs. Collectively, the name/value pairs are the properties of a BIG-IP®system
conguration. For iControl REST, the name/value pairs can be thought of as property name and property
value.
In a REST call, declare the format of the object to post . For iControl REST, specify the format
application/json. In a curl command, for example, specify the HTTP header -H "Content-Type:
application/json" to declare JSON format:
curl -k -u username:password -H "Content-Type: application/json"
-X http-method uri
Within the JSON body, dene the name of the conguration object. Then include the property names and
values for the object, using the same names and properties that appear in the response to a GET request for
a similar object. Any properties that you omit revert to the existing values, for a PUT request, or their default
values, for a POST request. If you use a tool like curl, you can specify the JSON body in the command line.
Several examples in this guide demonstrate the inclusion of a JSON body from the command line.
Creating a new resource with iControl
With the iControl®REST API, you can add a new resource to a BIG-IP®system by using the POST method
on an iControl REST collection, and specifying the resource to create as a JSON body. When you create a
resource, iControl REST sets all unspecied properties to their default values.
To add a new conguration object, specify the name of the resource as a JSON name/value pair and the
path to the collection in the URI.
POST https://192.168.25.42/mgmt/tm/ltm/pool
{ "name":"tcb-pool-0" }
The response to the POST request shows a new conguration object.
{ "allowNat" : "yes",
"allowSnat" : "yes",
"fullPath" : "tcb-pool-0",
"generation" : 5,
"ignorePersistedWeight" : "disabled",
"ipTosToClient" : "pass-through",
"ipTosToServer" : "pass-through",
"kind" : "tm:ltm:pool:poolstate",
"linkQosToClient" : "pass-through",
"linkQosToServer" : "pass-through",
"loadBalancingMode" : "round-robin",
"membersReference" : { "isSubcollection" : true,
"link" :
"https://localhost/mgmt/tm/ltm/pool/~Common~tcb-pool-0/members?ver=11.6.0"
},
"minActiveMembers" : 0,
"minUpMembers" : 0,
"minUpMembersAction" : "failover",
"minUpMembersChecking" : "disabled",
"name" : "tcb-pool-0",
"queueDepthLimit" : 0,
"queueOnConnectionLimit" : "disabled",
"queueTimeLimit" : 0,
"reselectTries" : 0,
"selfLink" : "https://localhost/mgmt/tm/ltm/pool/tcb-pool-0?ver=11.6.0",
"serviceDownAction" : "none",
"slowRampTime" : 10
}
After you create a new pool object by making a POST request, you can use the object.
Modifying a resource with PATCH
Using the PATCH method, you can modify properties of a resource without affecting any other properties.
To modify an object in the BIG-IP®system conguration, specify the resource in the URI. Do not specify
a collection in the URI.
PATCH https://192.168.25.42/mgmt/tm/pool/~Common~tcb-pool2
{"member": [{:name":"192.168.25.32:80", "description":"Tertiary web server"}]
}
The response to the PATCH request shows the changes to the resource.
{
"kind":"tm:ltm:pool:poolstate",
40
POST and PUT requests
"name":"tcb-pool2",
"partition":"Common",
"fullPath":"/Common/tcb-pool2",
"generation":59,
"selfLink":"https://../mgmt/tm/ltm/pool/~Common~tcb-pool2?ver=11.5.0",
"allowNat":"yes",
"allowSnat":"yes",
"ignorePersistedWeight":"disabled",
"ipTosToClient":"pass-through",
"ipTosToServer":"pass-through",
"linkQosToClient":"pass-through",
"linkQosToServer":"pass-through",
"loadBalancingMode":"round-robin",
"minActiveMembers":0,
"minUpMembers":0,
"minUpMembersAction":"failover",
"minUpMembersChecking":"disabled",
"queueDepthLimit":0,
"queueOnConnectionLimit":"disabled",
"queueTimeLimit":0,
"reselectTries":0,
"slowRampTime":10,
"membersReference":{
"link":"https://../mgmt/tm/ltm/pool/~Common~tcb-pool2/members?ver=11.5.0",
"isSubcollection":true
}
}
After completing the PATCH request, you can view the change to the individual resource.
About read only properties
If you specify a read only property with a PUT or POST method, iControl®REST accepts the request and
generates an error response. If you specify other properties in addition to the read only property, a valid
PUT or POST request will not generate an error, despite the inclusion of the read only property, .
For example, the following curl command species a read only property in an existing cm device object:
timeZone. The response from iControl®REST indicates a missing property name. In this situation, iControl®
REST ignores the read only property and generates the error message shown in the second block.
curl -k -u admin:admin -H "Content-Type: \
application/json" -X PUT -d \
'{"time-zone":"EDT"}' \
https://192.168.25.42/mgmt/tm/cm/device/bigip1
{
"code":400,
"message":"one or more properties must be specified",
"errorStack":[
]
}
41
iControl®REST API User Guide
Adding or modifying in a specific partition
To add or modify a resource in an administrative partition, add the partition property to the JSON body to
modify conguration objects. Use the query option on the command line, or include a partition property
in the JSON body. Keep in mind that the $lter query parameter applies to GET requests only.
To modify a conguration object with a PUT method, identify the object's partition in the partition
property.
This example uses the POST method to create a resource in a partition other than the Common partition.
Specify the name of the resource, and the partition in which to create it, in the JSON body. The response
to the request is shown in the third block.
POST https://192.168.25.42/mgmt/tm/ltm/pool
{ "name":"tcb-pool2", "partition":"~fw_objs" }
{
"kind":"tm:ltm:pool:poolstate",
"name":"tcb-pool2",
"partition":"fw_objs",
"fullPath":"/fw_objs/tcb-pool2",
"generation":7810,
"selfLink":"https://localhost/mgmt/tm/ltm/pool/~fw_objs~tcb-pool2?ver=11.5.0",
"allowNat":"yes",
"allowSnat":"yes",
"ignorePersistedWeight":"disabled",
"ipTosToClient":"pass-through",
"ipTosToServer":"pass-through",
"linkQosToClient":"pass-through",
"linkQosToServer":"pass-through",
"loadBalancingMode":"round-robin",
"minActiveMembers":0,
"minUpMembers":0,
"minUpMembersAction":"failover",
"minUpMembersChecking":"disabled",
"queueDepthLimit":0,
"queueOnConnectionLimit":"disabled",
"queueTimeLimit":0,
"reselectTries":0,
"slowRampTime":10,
"membersReference":{
"link":"https://../mgmt/tm/ltm/pool/~fw_objs~tcb-pool2/members?ver=11.5.0",
"isSubcollection":true
}
}
Following the creation of a new conguration object, this example modies the member collection by using
a PUT request. The URI includes the full path to the resource to modify. Specify the partition property, as
42
POST and PUT requests
well as any properties you wish to modify. The partition property in the JSON body matches the folder
name. The response to the request is shown in the third block.
PUT https://192.168.25.42/mgmt/tm/ltm/pool/~fw_objs~tcb-pool2
{ "name":"tcb-pool2", "partition":"/fw_objs",
"members": [ {"name":"192.168.25.32", "description":"Marketing server"} ] }
{
"kind":"tm:ltm:pool:poolstate",
"name":"tcb-pool2",
"partition":"fw_objs",
"fullPath":"/fw_objs/tcb-pool2",
"generation":7914,
"selfLink":"https://localhost/mgmt/tm/ltm/pool/~fw_objs~tcb-pool2?ver=11.5.0",
"allowNat":"yes",
"allowSnat":"yes",
"description":"This pool exists in the fw_objs partition.",
"ignorePersistedWeight":"disabled",
"ipTosToClient":"pass-through",
"ipTosToServer":"pass-through",
"linkQosToClient":"pass-through",
"linkQosToServer":"pass-through",
"loadBalancingMode":"round-robin",
"minActiveMembers":0,
"minUpMembers":0,
"minUpMembersAction":"failover",
"minUpMembersChecking":"disabled",
"queueDepthLimit":0,
"queueOnConnectionLimit":"disabled",
"queueTimeLimit":0,
"reselectTries":0,
"slowRampTime":10,
"membersReference":{
"link":"https://../mgmt/tm/ltm/pool/~fw_objs~tcb-pool2/members?ver=11.5.0",
"isSubcollection":true
}
}
About relative partitions and folder names
If you use a relative folder path within a partition body, iControl®REST interprets the folder name relative
to the parent partition. Set the parent partition by specifying the $filter=partition eq folder-name
query parameter in the URI, or the partition property in the JSON body, depending on the type of request.
The $filter query parameter applies to GET requests, whereas the partition property in a JSON body
applies to PATCH, POST or PUT requests. For example, if the $filter=partition query option is set
to /eu and the JSON body includes a reference to the france folder, iControl®REST interprets the folder
path as /eu/france. To avoid ambiguity with partition and folder names, use absolute paths for all folders
in JSON body, such as /eu/france.
The $filter query parameter differs from the OData query parameter in that it only supports ltering by
partition names in iControl REST.
43
iControl®REST API User Guide
Deleting Access Policy Manager resources
Using iControl®REST, you can delete Access Policy Manager™(APM™) resources.
To delete an Access Policy Manager (APM) resource, such as a sample-log-setting resource, make
a DELETE request to a resource in the /mgmt/tm/apm/log-setting namespace.
DELETE https://192.168.25.42/mgmt/tm/apm/log-setting/sample-log-setting
iControl REST does not generate a response for a DELETE request but you can verify the deletion of
the resource.
44
POST and PUT requests
Partitions
About administrative partitions
Many types of BIG-IP®system objects, such as proles and pools, reside in administrative partitions.
Partitions are containers with administrative boundaries that you control with access permissions. Through
restricted access to administrative partitions, the security model imposes greater control over the conguration
objects,which reduces the likelihood of inadvertent changes to the system conguration.
The Common partition contains all default proles, precongured monitors, default authentication iRules,
the root and admin user accounts, and route domain 0, which is the default route domain. The Common
partition is created by the BIG-IP®installation process. If there are no other administrative partitions on a
system, all objects will be created in the Common partition. All administrators can access the Common partition.
Administrators that have the Administrator or Resource Administrator role associated with their
user account can create partitions.
When you create other partitions, you can associate a user account to that partition and grant permissions
to administer that partition. In most circumstances, you either grant a user access to a single partition or
universal access to all partitions, A user with access to a single partition can only create objects in that
partition. If you grant a user universal access to all partitions, the user must select the partition in which to
create an object by specifying the sys/folder namespace and the folder name in the request URI.
Every partition has a corresponding folder in the sys/folder namespace, including the Common partition,
which has an associated /Common folder. You can specify a namespace in an iControl®REST URI when
you create or delete a partition.
Important: You cannot remove the Common partition, regardless of your level of administrative access.
Creating folders
You can use iControl®REST methods and properties to create a folder for administrative purposes. There
are three different approaches to creating a folder.
Important: You must make a separate request to iControl REST to assign user permissions on a partition.
1. You can create a root-level folder by specifying the path and folder name as the name of the resource.
To create a root-level folder named fw_objs, make a POST request as shown:
POST https://192.168.25.42/mgmt/tm/sys/folder
{
"name": "fw_objs",
"partition": "/"
}
The resulting object will have the following properties:
{
"deviceGroup": "none",
"fullPath": "/fw_objs",
"generation": 393,
"hidden": "false",
"inheritedDevicegroup": "true",
"inheritedTrafficGroup": "true",
"kind": "tm:sys:folder:folderstate",
"name": "fw_objs",
"noRefCheck": "false",
"selfLink": "https://localhost/mgmt/tm/sys/folder/~fw_objs?ver=...",
"subPath": "/",
"trafficGroup": "/Common/traffic-group-1",
"trafficGroupReference": {
"link":
"https://localhost/mgmt/tm/cm/traffic-group/~Common~traffic-group-1?ver=..."
}
}
2. If you want to create a folder named fw_objs in the /Common folder, you can do so by specifying just
the folder name in the name property.
To create a folder named fw_objs, in the /Common folder, make a POST request as shown:
POST https://192.168.25.42/mgmt/tm/sys/folder
{
"name": "fw_objs"
}
In this step, the path is not specied and the folder is created in the Common partition, which is the default
partition for iControl REST. If you compare the resulting object from the previous step with the resulting
object from this step, you will notice that the current object does not include either the subPath property
or the partition property. When you create a folder in the Common partition, iControl REST does not
include the enclosing partition property in the response.
The resulting object has the following properties:
{
"deviceGroup": "none",
"fullPath": "fw_objs",
"generation": 403,
"hidden": "false",
"inheritedDevicegroup": "true",
"inheritedTrafficGroup": "true",
"kind": "tm:sys:folder:folderstate",
"name": "fw_objs",
"noRefCheck": "false",
"selfLink": "https://localhost/mgmt/tm/sys/folder/fw_objs?ver=...",
"trafficGroup": "/Common/traffic-group-1",
"trafficGroupReference": {
"link":
"https://localhost/mgmt/tm/cm/traffic-group/~Common~traffic-group-1?ver=..."
}
}
3. Create a hierarchy of folders by specifying additional properties of the folder object.
46
Partitions
To create the folder /fw_objs/fw_objs, use a POST request and specify the partition,subPath,
and name.
POST https://192.168.25.42/mgmt/tm/sys/folder
{
"partition": "/",
"subPath": "fw_objs",
"name": "fw_objs"
}
You could have specied the partition property in this example as /fw_objs, instead of specifying the
partition and the sub path separately. As a general approach, everything between the top-level slash ('/')
and the partition name constitutes a sub path. Otherwise, a single name constitutes a partition name
when preceded by a top-level slash ('/'), as shown in the rst example.
The resulting object has the following properties:
{
"deviceGroup": "none",
"fullPath": "/fw_objs/fw_objs",
"generation": 410,
"hidden": "false",
"inheritedDevicegroup": "true",
"inheritedTrafficGroup": "true",
"kind": "tm:sys:folder:folderstate",
"name": "fw_objs",
"noRefCheck": "false",
"partition": "fw_objs",
"selfLink":
"https://localhost/mgmt/tm/sys/folder/~fw_objs~fw_objs?ver=...",
"trafficGroup": "/Common/traffic-group-1",
"trafficGroupReference": {
"link":
"https://localhost/mgmt/tm/cm/traffic-group/~Common~traffic-group-1?ver=..."
}
}
Deleting an administrative partition
An administrative partition, other than Common, can be deleted with a DELETE request. In the URI, specify
the folder name of the partition to delete, and submit the request without a JSON body. Because a folder
name includes a forward slash, the folder name must be specied with a tilde character.
Important: You can only delete a partition if it is empty. Remove all objects in the partition before you
attempt to delete the partition.
To delete a partitionspecify the DELETE method and the folder namespace /mgmt/tm/sys/folder/
in the URI. Replace each forward slash (/) in the folder name with a tilde character (~).
47
iControl®REST API User Guide
In this example, the iControl®REST request deletes the /fw_objs partition from the system conguration.
The response includes a response code to indicate success or failure, but the response does not produce a
JSON body unless there is an error in the request.
curl -k -u admin:admin -H "Content-Type: \
application/json" -X DELETE \
https://192.168.25.42/mgmt/tm/sys/folder/~fw_objs \
|python -m json.tool
48
Partitions
Transactions
About the iControl REST transaction model
Some administrative actions in the BIG-IP®system require multiple commands, and in some cases, those
commands depend on the successful outcome of other commands. To accommodate complex processes
like these, iControl®REST offers transactions, where a transaction is a sequence of individual commands
performed as a single unit of work. Transactions work similarly to relational database systems. When
handling a database transaction, a relational database system commits the changes if all of the SQL commands
run successfully. If any of the SQL commands fail, the relational database system rolls back all of the
changes. iControl REST supports a similar feature where a sequence of individual web service requests acts
as a single unit of work.
The iControl REST methods you use to create, delete, modify, or query a resource make up the individual
commands of a transaction. However, instead of processing each command on arrival, a transaction aggregates
multiple commands into a single atomic operation. In this manner, an atomic transaction guarantees the
all-or-none semantics of a transaction. A transaction completes successfully if all of the individual commands
in the transaction complete successfully. Conversely, if any of the commands in a transaction fail, then the
entire transaction fails. If the transaction fails, iControl REST rolls back any commands that completed
prior to the operation that failed.
About iControl REST transaction phases
The life cycle of a transaction progresses through three phases:
Creation
This phase occurs when the transaction is created using a POST request.
Modification
This phase occurs when commands are added to the transaction, or changes are made to the sequence
of commands in the transaction.
Commit
This phase occurs when iControl REST runs the transaction.
iControl REST reserves a namespace for transactions. All commands to create, delete, modify, or query
resources within the framework of a transaction use the iControl REST transaction resource namespace
/mgmt/tm/transaction. This namespace prevents a command from automatically being run by iControl
REST when it receives a request. iControl REST creates a transaction in response to a POST request that
includes an empty JSON body. In response, iControl REST generates an identier for the transaction. When
you create a transaction, the transaction resource associates three properties with that transaction:
• A read-only transId property that identies a transaction for the life of the transaction.
• A writeable state property that indicates the state of the transaction. Values for this property are:
STARTED,UPDATING,VALIDATING,COMPLETED, or FAILED. Other than when you commit a transaction,
you never change the value of the writeable property state.
• A read-only timeoutSeconds property that species the time period during which to add commands
to the transaction. iControl REST sets the value to 120 seconds.
In the modication phase, iControl REST adds a command to a transaction, if a request includes a valid
transaction identier. As with a request to create a transaction, a request to add a command is a POST
method that species the transaction namespace. Aside from adding commands to a transaction, you can
delete a command from a transaction or change the order of the commands in a transaction. Commands are
added to a transaction in the order they are received. iControl REST assigns a command identier to every
command added to a transaction. Any changes to an existing transaction, such as a change to the order of
the commands, must include a transaction identier and a command identier. Deletion of a command also
requires a transaction identier and a command identier.
The nal phase of a transaction is the commit phase. When you are ready to run a transaction, you make a
PATCH request and specify the state of the transaction to indicate to iControl REST that it should run the
transaction. You must specify the transaction identier in your request.
Note: In iControl REST version 11.6.0, you can create multiple transactions per user.
About transaction validation
The iControl®REST API provides a property to validate a transaction without actually making any
conguration changes to the BIG-IP®system. By using this property, iControl REST determines the likelihood
of a successful transaction prior to any attempt to commit the transaction. To use this feature, create a
transaction as you normally would and specify the validateOnly property in a JSON body when you
commit the transaction with a PATCH request. iControl REST returns HTTP 200 OK if the transaction
request does not generate any errors.
To validate a transaction request, specify "validateOnly": true in the JSON body of a PATCH request.
The value of the property defaults to false. If you specify the property in any other phase than the commit
phase, iControl REST ignores the property.
Creating an iControl REST transaction
Transactions allow you to run a sequence of commands as a single unit of work. Before you can populate
a transaction, you must create a transaction by specifying the transaction endpoint.
1. To create a transaction, use the POST method with the /tm/transaction namespace. You must include
an empty JSON body with the request.
POST https://192.168.25.42/mgmt/tm/transaction
{ }
If the POST request is successful, the response contains the transaction identier. You must include the
transaction identier in a request to indicate that an operation is part of a transaction. Note the three
transactions properties in the response: transId,state, and timeoutSeconds.
{
"transId":1389812351,
"state":"STARTED",
"timeoutSeconds":120,
"kind":"tm:transactionstate",
"selfLink":"https://localhost/mgmt/tm/transaction/1389812351?ver=11.5.0"
}
50
Transactions
2. To view the existing transactions, specify one of the transaction endpoints in a query request. To retrieve
all transactions in a collection, specify the URI https://<server name>/mgmt/tm/transaction.
To retrieve a specic transaction, specify the URI https://<server
name>/mgmt/tm/transaction/<transId>, where transId is the identier for the transaction. If
you do not add a command to a transaction within one hundred and twenty (120) seconds, the transaction
expires.
GET https://192.168.25.42/mgmt/tm/transaction
GET https://192.168.25.42/mgmt/tm/transaction/<transId>
Modifying a transaction
After you create a transaction, you can populate the transaction by adding commands. Individual commands
comprise the operations that a transaction performs. Commands are added in the order they are received
but you can delete commands or change the order of the commands in the transaction.
1. To add a command to a transaction, use the POST method and specify the
X-F5-REST-Coordination-Id HTTP header with the transaction ID value from the example
(1389812351). In the example, the request creates a new pool and adds a single member to the pool.
POST https://192.168.25.42/mgmt/tm/ltm/pool
X-F5-REST-Coordination-Id:1389812351
{
"name":"tcb-xact-pool",
"members": [ {"name":"192.168.25.32:80","description":"First pool for
transactions"} ]
}
The response indicates that iControl®REST added the operation to the transaction.
{
"transId":1389812351,
"state":"STARTED",
"timeoutSeconds":120,
"kind":"tm:transactionstate",
"selfLink":"https://localhost/mgmt/tm/transaction/1389813931?ver=11.5.0"
}
2. (Optional) To query a single transaction, specify the URI https://<server
name>/mgmt/tm/transaction/transId, where transId is the identier of the transaction.
GET https://192.168.25.42/mgmt/tm/transaction/138912351
51
iControl®REST API User Guide
3. (Optional) To obtain a list of commands in a transaction, specify the URI https://<server
name>/mgmt/tm/transaction/transId/commands, where transId is the identier of the
transaction.
GET https://192.168.25.42/mgmt/tm/transaction/138912351/commands
4. (Optional) To obtain the details of a single operation, specify the URI https://<server
name>/mgmt/tm/transaction/transId/commands/commandId, where transId is the identier
of the transaction, and commandId is the identier of the operation.
GET https://192.168.25.42/mgmt/tm/transaction/138912351/commands/1
5. (Optional) To remove a command from a transaction, specify the URI https://<server
name>/mgmt/tm/transaction/transId/commands/commandId, where transId is the identier
of the transaction, and commandId is the identier of the command. iControl REST renumbers the
remaining commands in the transaction.
DELETE https://192.168.25.42/mgmt/tm/transaction/138912351/commands/1
6. (Optional) To change the evaluation order, specify the URI https://<server
name>/mgmt/tm/transaction/transId/commands/commandId, where transId is the identier
for the transaction, and commandId is the identier for the command. In the JSON message body,
specify a key/value pair "evalOrder":y, where yrepresents a new evalOrder value. This action
moves the command.
Committing an iControl REST transaction
After you nish adding commands to a transaction, and you are satised with the evaluation order of the
commands, you can run the sequence of commands by committing the transaction. Each operation in the
transaction must complete successfully. If an operation fails, the transaction rolls back any changes and
returns an error. If you choose not to run the transaction at this point, you can delete the transaction.
1. To commit a transaction, use the PATCH method. In the JSON body, specify the state of the transaction
as VALIDATING.
PATCH https://localhost/mgmt/tm/transaction/1389812351
{ "state":"VALIDATING" }
2. (Optional) To delete a transaction, specify the URI
https://localhost/mgmt/tm/transaction/transId, where transId is the transaction identier.
iControl®REST deletes all operations associated with this transaction.
DELETE https://localhost/mgmt/tm/transaction/1389812351
52
Transactions
About iControl REST asynchronous tasks
iControl®REST requests run in a synchronous manner and complete within a short period of time, usually
in a matter of seconds. A single iControl REST request may run for a longer period of time, and do so
without providing any indication of the eventual success or failure of the request. In some situations, a
request may time out prior to completion of the request.
iControl REST addresses the problems associated with a long-running request by allowing asynchronous
tasks for some endpoints. A long-running request is a request that routinely takes more than 60 seconds to
complete. If the endpoint you are targeting exists in the table of endpoints, you should consider making
your request an asynchronous task. A POST request to an asynchronous task URI noties iControl REST
to create a task and then respond to additional requests for task state. As part of the initial response to the
POST request, iControl REST returns a JSON body that includes a self link that you use to poll the task.
To monitor an asynchronous task, you create a task and then poll the task by identier to determine the
state of the task. All asynchronous tasks are in one of the following states: UPDATING,VALIDATING,
COMPLETED, or FAILED. iControl REST sets the initial state of a task to UPDATING and then returns an
HTTP 200 status code to indicate the creation of the task.
When the asynchronous task completes, iControl REST changes the state of the task to COMPLETED. The
response to a polling request for a completed task includes a JSON body with a self link to the task results.
After you review the results, you should delete the results and then delete the task, in that order.
Asynchronous task endpoints
This table lists common iControl®REST API endpoints along with corresponding asynchronous task
endpoints, organized by function.
URI (asynchronous)URI (synchronous)Description
POST tm/task/sys/congPOST tm/sys/congSave/Load cong
POST tm/task/sys/ucsPOST tm/sys/ucsSave/Load UCS
POST tm/task/sys/geoipPOST tm/sys/geoipLoad IP geolocation
data
POST tm/task/sys/classication-signaturePOST tm/sys/classication-signatureLoad classication
signatures
POST tm/task/sys/failoverPOST tm/sys/failoverFailover
POST tm/task/ltm/dns-express-dbPOST tm/ltm/dns-express-dbLoad
DNS-Express®DB
POST
tm/task/ltm/classication/urldb-feed-list
POST
tm/ltm/classication/urldb-feed-list
Load URL DB feed
list
POST tm/task/ltm/classication/signaturesPOST tm/ltm/classication/signaturesLoad classication
signatures
POST
tm/task/ltm/classication/update-signatures
POST
tm/ltm/classication/update-signatures
Update signatures
POST tm/task/apm/epsec/epsec-packagePOST tm/apm/epsec/epsec-packageInstall EPSEC
package
POST tm/task/vcmp/guestPOST tm/vcmp/guestCreate vCMP®
guest
53
iControl®REST API User Guide
URI (asynchronous)URI (synchronous)Description
POST tm/task/cli/scriptPOST tm/cli/scriptRun CLI scripts
POST tm/task/wom/verify-congPOST tm/wom/verify-congVerify WOM
conguration
POST tm/task/wom/diagnose-connPOST tm/wom/diagnose-connDiagnose WOM
connections
POST tm/task/wam/policyPOST tm/wam/policyLoad/Save/Publish
WAM policy
POST tm/task/security/rewall/fqdn-entityPOST tm/security/rewall/fqdn-entityLoad rewall
FQDN entity
POST
tm/task/security/ip-intelligence/feed-list
POST
tm/security/ip-intelligence/feed-list
Load IP intelligence
feed list
POST
tm/task/security/anti-fraud/signatures-update
POST
tm/security/anti-fraud/signatures-update
Load/update
anti-fraud
signatures
POST
tm/task/security/anti-fraud/engine-update
POST
tm/security/anti-fraud/engine-update
Load/update
anti-fraud engine
update
POST tm/task/pem/subscribersPOST tm/pem/subscribersLoad PEM
subscribers
POST tm/task/ilx/pluginPOST tm/ilx/pluginStart/Stop/Restart
ILX plug-in
POST tm/task/cm/cong-syncPOST tm/cm/cong-syncRun cong sync
POST tm/task/cm/add-to-trustPOST tm/cm/add-to-trustAdd device to trust
domain
POST tm/task/cm/remove-from-trustPOST tm/cm/remove-from-trustRemove device
from trust domain
Using an asynchronous task
An asynchronous task provides an alternative to a long-running synchronous task.
1. To create an asynchronous task, locate the endpoint for the task in the asynchronous task endpoints
table. For this example, identify the corresponding endpoint for /tm/sys/ucs (/tm/task/sys/ucs)
and supply a JSON body.
POST https://192.168.25.42/mgmt/tm/task/sys/ucs
{
"command": "save",
"name": "myUcs"
}
54
Transactions
In the response from the request, locate the reference endpoint (selfLink) to query for the task state.
You will use the endpoint in the subsequent steps.
{
"command":"save",
"name":"myUcs",
"selfLink":"https://localhost/mgmt/tm/task/sys/ucs/1234&ver=12.0.0",
"_taskID":"1234",
"_taskState":"UPDATING",
"_taskTimeInStateMs":0,
"_taskResultLink":"https://localhost/mgmt/tm/task/sys/ucs/1234/result&ver=12.0.0",
"_taskWaitTime":30000
}
2. To start the task, modify the state of the task in a PUT request and specify the selfLink as the endpoint.
Specify VALIDATING as the value of the _taskState property. You may safely omit the version
parameter in the URI.
Note that if you do not modify the state of the task, the task will not run and eventually will be deleted.
PUT https://192.168.25.42/mgmt/tm/task/sys/ucs/1234
{
"_taskState": "VALIDATING"
}
If the request was successful, you should see a response similar to the following:
{
"_code": 202,
"errorStack": [],
"message": "Task will execute asynchronously."
}
3. Verify the state of the asynchronous task.
To monitor the progress of the task, you can periodically make a GET request to the reference endpoint
to check the state of the task.
Note: Aload ucs task invokes a restart, which affects data in memory, such as the task list. The step
of polling for a task will not work in this case.
GET https://192.168.25.42/mgmt/tm/task/sys/ucs/1234
The response at some point should indicate that the task has completed.
{
"_taskId":1234,
"_taskResultLink":"https://localhost/mgmt/tm/task/sys/ucs/1234/result&ver=12.0.0",
"_taskState":"COMPLETED",
"_taskTimeInStateMs":0,
"selfLink":"https://localhost/mgmt/tm/task/sys/ucs/1234&ver=12.0.0"
}
55
iControl®REST API User Guide
4. When the task completes, make a GET request to the result endpoint.
GET https://192.168.25.42/mgmt/tm/task/sys/ucs/1234/result
In this example, you submitted and started an asynchronous task, and viewed the results of the task.
After you view the results of the task, delete the results and then delete the initial task by URI.
56
Transactions
Commands
About other tmsh global commands
Not all Trafc Management Shell (tmsh) Reference commands map directly to HTTP methods. For a list
or show request of a resource, a GET request maps well to the requested operation, but the reference includes
global commands that do not directly correspond to an HTTP method. iControl®REST implements the
following set of tmsh commands:
•cp
•generate
•install
•load
•mv
•publish
•reboot
•restart
•reset_stats
•run
•save
•send-mail
•start
•stop
iControl REST supports these tmsh commands by mapping a command, as well as options, to JSON format.
The iControl REST format for tmsh commands follows this general approach:
• Use the POST method.
• Specify a namespace for the tmsh command in the URI.
• Specify the command and options as the values of the properties in the JSON body.
To run the command, use the POST method and specify an absolute URI, such as
https://192.168.25.42/mgmt/tm/sys/application/template, along with the JSON body for
the command. In each example, a relative URI is used in the request body.
Using the cp command
Utility commands do not have a direct mapping to an HTTP method, so you must use the POST method
and specify an absolute URI, such as https://192.168.25.42/mgmt/tm/sys/application/template,
along with a JSON body that species the name of the utility command.
To copy using the cp command, make an iControl®REST request with the POST method and specify
the properties in a JSON body.
To copy a le using the cp command, make a POST request. In the JSON body, specify the command, le
name, and target le name.
POST /mgmt/tm/sys/application/template
{
"command":"cp",
"name":"tempt1",
"target":"tempt2",
}
Using the generate command
Global commands like generate do not have a direct mapping to an HTTP method, so you must use the
POST method and specify an absolute URI, such as https://192.168.25.42/mgmt/tm/ltm/rule,
along with a JSON body that species the name of the command.
To generate signed scripts using the generate command, make an iControl®REST request with the
POST method and specify the properties in a JSON body.
To generate a signed script using the generate command, make a POST request. In the JSON body, specify
the command, script name, options, and a signing key. The signing key property name uses a hyphenated
name instead of the came case naming convention of iControl®REST.
POST /mgmt/tm/ltm/rule
{
"command":"generate",
"name":"rule1",
"options":[
{
"signature":true
}
],
"signing-key":"key1"
}
Using the install command
Global commands like install do not have a direct mapping to an HTTP method. So you must use the
POST method and specify an absolute URI, such as
https://192.168.25.42/mgmt/tm/sys/software/image, along with a JSON body that species
the name of the command. This topic shows two examples of the install command.
58
Commands
1. To install and update components using the install command, make an iControl®REST request with
the POST method and a JSON body.
POST /mgmt/tm/sys/software/image
{
"command":"install",
"name":"BIGIP-11.5.0.930.400.iso",
"volume":"HD1.3"
}
2. To perform the same task and take advantage of the options for the install command, follow the previous
steps and specify the create-volume and reboot options in the JSON body. The create volume
property name uses a hyphenated name instead of the camel-casing convention of iControl REST.
POST /mgmt/tm/sys/software/image
{
"command":"install",
"options":[
{
"create-volume":true
},
{
"reboot":true
}
],
"name":"BIGIP-11.4.0.737.400.42.iso",
"volume":"HD1.1"
}
Using the load command
Global commands like load do not have a direct mapping to an HTTP method, so you must use the POST
method and specify an absolute URI, such as https://192.168.25.42/mgmt/tm/sys/config, along
with a JSON body that species the name of the command.
Load BIG-IP®system conguration using the load command by making an iControl®REST request
with the POST method and a JSON body.
To replace the running conguration using the load command, make a POST request. In the JSON body,
specify the command.
POST /mgmt/tm/sys/config
{
"command":"load",
"name": "default"
}
59
iControl®REST API User Guide
Using the mv command
Global commands like mv do not have a direct mapping to an HTTP method, so you must use the POST
method and specify an absolute URI, such as https://192.168.25.42/mgmt/tm/cm/device, along
with a JSON body that species the name of the command.
To copy using the mv command, make an iControl®REST request with the POST method and specify
the properties in a JSON body.
To move or rename an object using the mv command, make a POST request. In the JSON body, specify the
command, name, and target:
POST /mgmt/tm/cm/device
{
"command":"mv",
"name":"bigip1",
"target":"selfdevice2",
}
Using the publish command
Global commands, such as publish, do not have a direct mapping to an HTTP method, so you must use the
POST method and specify an absolute URI, such as https://192.168.25.42/mgmt/tm/asm/policy,
along with a JSON body that species the name of the command.
Publish changes in a policy by making an iControl®REST request with the POST method and specifying
the properties in a JSON body.
In the JSON body, specify the command, name of the policy, and the application service. The application
service property name uses a hyphenated name instead of the camel case naming convention of iControl
REST.
POST /mgmt/tm/asm/policy
{
"command":"publish",
"name":"testpolicy",
"app-service":"service",
}
Using the reboot command
Global commands like reboot do not have a direct mapping to an HTTP method, so you must use the POST
method and specify an absolute URI, such as https://192.168.25.42/mgmt/tm/sys, along with a
JSON body that species the name of the command.
60
Commands
Reboot a system, or boot a system into a different volume by making an iControl®REST request with
the POST method and specifying the properties in a JSON body.
To reboot a system using the reboot command, make a POST request. In the JSON body, specify the
command.
POST /mgmt/tm/sys
{
"command":"reboot"
}
Using the restart command
Global commands like restart do not have a direct mapping to an HTTP method, so you must use the POST
method and specify an absolute URI, such as https://192.168.25.42/mgmt/tm/sys/service, along
with a JSON body that species the name of the command.
Restart a service by making an iControl®REST request with the POST method and specifying the
properties in a JSON body.
To restart a service using the restart command, make a POST request. In the JSON body, specify the
command and the name of the service to restart.
POST /mgmt/tm/sys/service
{
"command":"restart",
"name":"icrd"
}
Using the reset-stats command
Global commands like reset-stats do not have a direct mapping to an HTTP method, so you must use the
POST method and specify an absolute URI, such as https://192.168.25.42/mgmt/tm/ltm/virtual,
along with a JSON body that species the name of the command.
Reset statistics for a component by making an iControl®REST request with the POST method and
specifying the properties in a JSON body.
61
iControl®REST API User Guide
To reset statistics for a component using the reset-stats command, make a POST request. In the JSON body,
specify the command and the name of the component.
POST /mgmt/tm/ltm/virtual
{
"command":"reset-stats",
"name":"http_vs1"
}
Using the run command
Global commands like the run command do not have a direct mapping to an HTTP method, so you must
use the POST method and specify an absolute URI, such as
https://192.168.25.42/mgmt/tm/util/ping, along with a JSON body that species the name of
the command. In addition to the ping example, you can also use the run command to synchronize the
conguration in a high-availability (HA) pair. This topic shows examples of both, to highlight the applicability
of the run command.
1. To run a program, make an iControl®REST request with the POST method and specify the properties
in a JSON body.
POST https://192.168.25.42/mgmt/tm/util/ping
{
"command":"run",
"utilCmdArgs":"1.1.1.1 -c 1 -i 10"
}
2. To sync the conguration to a standby server in an active-standby HA pair, run the config sync
command by making an iControl REST request as shown.
POST https://192.168.25.42/mgmt/tm/cm
{
"command": "run",
"utilCmdArgs": "config-sync to-group <Device Group Name>"
}
Note: You must supply a value for the Device Group Name in the example.
62
Commands
Using the save command
Global commands like save do not have a direct mapping to an HTTP method, so you must use the POST
method and specify an absolute URI, such as https://192.168.25.42/mgmt/tm/sys/config, along
with a JSON body that species the name of the command.
Save the running conguration of a BIG-IP®system by making an iControl®REST request with the
POST method and specifying the properties in a JSON body.
To save the running conguration using the save command, make a POST request. In the JSON body,
specify the command.
POST /mgmt/tm/sys/config
{
"command":"save"
}
To use the options available for the save command, specify the command and the options in a JSON body.
{
"command":"save",
"options":[
{
"file":"configfile.scf"
}
]
}
Using the send-mail command
Global commands like send-mail do not have a direct mapping to an HTTP method, so you must use the
POST method and specify an absolute URI, such as
https://192.168.25.42/mgmt/tm/analytics/application-security/report, along with a
JSON body that species the name of the command.
Send an e-mail to recipients by making an iControl®REST request with the POST method and specifying
the properties in a JSON body.
To send e-mail using the send-mail command, make a POST request. In the JSON body, specify the command.
Specify the options, as well as the recipients, in the JSON body. Several of the property names use a
hyphenated name instead of the camel case naming convention of iControl®REST.
POST /mgmt/tm/analytics/application-security/report
{
"command":"send-mail",
63
iControl®REST API User Guide
"view-by":"ip",
"format":"pdf",
"email-addresses":[
"wchen@f5.com"
],
"measures":[
"illegal-transactions"
],
"limit":20,
"order-by":[
{
"measure":"illegal-transactions",
"sort-type":"desc"
}
],
"smtp-config-override":"smtpserver"
}
Using the start command
Global commands like start do not have a direct mapping to an HTTP method, so you must use the POST
method and specify an absolute URI, such as
https://192.168.25.42/mgmt/tm/sys/icall/handler/perpetual, along with a JSON body that
species the name of the command.
Start a service by making an iControl®REST request with the POST method and specifying the properties
in a JSON body.
To start a service using the start command, make a POST request. In the JSON body, specify the command
and the name of the service.
POST /mgmt/tm/sys/icall/handler/perpetual
{
"command":"start",
"name":"perphd1"
}
Using the stop command
Global commands like stop do not have a direct mapping to an HTTP method, so you must use the POST
method and specify an absolute URI, such as
https://192.168.25.42/mgmt/tm/sys/icall/handler/perpetual, along with a JSON body that
species the name of the command.
Stop a service by making an iControl®REST request with the POST method and specifying the properties
in a JSON body.
64
Commands
To stop a service using the stop command, make a POST request. In the JSON body, specify the command
and the name of the service.
POST /mgmt/tm/sys/icall/handler/perpetual
{
"command":"stop",
"name":"perphd1"
}
65
iControl®REST API User Guide
Application Security Manager
Application Security Manager and iControl REST comparison
If you use Application Security Manager™(ASM™), you should understand how ASM differs from iControl
REST.
Application Security Manager™(ASM™) shares much in common with iControl®REST. As with any
organizing collection in iControl REST, ASM supports discovery of the API, common methods, as well as
a set of query parameters. However, ASM offers some features that distinguish it from iControl REST, as
outlined in the following list.
• ASM resource URIs include an MD5 hash that identies the resource.
•ASM implements a larger set of Open Data Protocol (OData) query parameters, functions, and operators.
• ASM does not implement custom query parameters, like expandSubcollections.
• ASM does not support the /stats endpoint.
• ASM supports tasks, not transactions.
The following table lists the HTTP methods that ASM supports.
DescriptionMethod
For both collections and other resources, ASM supports the GET method to retrieve or
search. The $filter query parameter support in ASM includes more options than
iControl REST.
GET
For both collections and other resources, ASM supports the POST method to create an
entity. A POST request must include a JSON body, although the JSON body may be
empty.
POST
For most collections, ASM supports the DELETE method. ASM supports the deletion
of subsets of collections that match a $filter query. For other resources, ASM supports
DELETE
the DELETE method. With the inclusion of a query parameter, ASM also supports the
option to delete multiple entities.
For collections or elements, ASM does not support the PUT method.PUT
For collections, ASM supports the PATCH method. In ASM, PATCH can update multiple
entities if you specify a query option in the URI. For other resources, ASM supports the
PATCH
PATCH method. The PATCH method updates specied properties; PATCH does not
reset or overwrite properties that are not specied in the request.
ASM implements OData Version 4 and provides some support for OData Version 3 string functions. ASM
supports the query options and functions, with restrictions, listed in the following table.
DescriptionParameter
Species a lter for a retrieve, update, or delete operation. In ASM, $filter
supports the contains,endswith,startswith, and substringofstring
functions. No math functions are supported.
$filter
Species a subset of the properties to appear in the result set.$select
DescriptionParameter
Species the number of rows to skip in the result set. The result set is chosen from
the remaining rows.
$skip
Species the rst nrows of the result set.$top
Species the inclusion of related entities in the result set.$expand
Species the order in which to display items. The $orderby parameter cannot
be applied to a subeld inside of an expanded eld, such as
$orderby=requestPolicy/name on /tm/asm/events/requests.
$orderby
As with iControl REST, ASM also supports comparison and logical operators as described by the OData
protocol. The following table lists the ASM operators.
DescriptionOperator
Equal to operator.eq
Not equal to operator.ne
Less than operator.lt
Less than or equal to operator.le
Greater than operator.gt
Greater than or equal to operator.ge
True if both operands are true operator.and
True if either operand is true. In ASM, $filter supports the or operator for
conditions that apply to one eld, such as (A eq 1 OR A eq 2).
or
Negation of operand operator.not
The following table lists the ASM namespaces.
DescriptionNamespace
Collection, read-only./tm/asm/attack-types
Collection that does not support update many or delete many requests./tm/asm/signatures
Collection, read-only./tm/asm/signature-statuses
Collection that does not support update many or delete many requests./tm/asm/signature-sets
Element/tm/asm/signatures-update
Collection, read-only./tm/asm/signature-systems
Collection, read-only./tm/asm/policy-templates
Collection that does not support update many or delete many requests.
Collections within this namespace:
/tm/asm/policies
• /tm/asm/policies/<MD5Hash>/methods
• /tm/asm/policies/<MD5Hash>/letypes
• /tm/asm/policies/<MD5Hash>/cookies
• /tm/asm/policies/<MD5Hash>/host-names
• /tm/asm/policies/<MD5Hash>/blocking-settings/violations
• /tm/asm/policies/<MD5Hash>/blocking-settings/evasions
• /tm/asm/policies/<MD5Hash>/blocking-settings/http-protocols
68
Application Security Manager
DescriptionNamespace
•/tm/asm/policies/<MD5Hash>/blocking-settings/web-services-securities
• /tm/asm/policies/<MD5Hash>/urls
• /tm/asm/policies/<MD5Hash>/parameters
• /tm/asm/policies/<MD5Hash>/urls/<MD5Hash>/parameters
• /tm/asm/policies/<MD5Hash>/whitelist-ips
• /tm/asm/policies/<MD5Hash>/gwt-proles
• /tm/asm/policies/<MD5Hash>/json-proles
• /tm/asm/policies/<MD5Hash>/xml-proles
• /tm/asm/policies/<MD5Hash>/signatures
• /tm/asm/policies/<MD5Hash>/signatures-sets
Retrieving Application Security Manager resources
Consistent with iControl®REST behavior, Application Security Manager™(ASM™) supports querying of
endpoints within the namespace /mgmt/tm/asm. As with any other organizing collection in iControl®
REST, you can make a GET request to discover the resources of ASM.
1. Make a request to the endpoint /mgmt/tm/asm to query for ASM resources.
2. To discover the resources of ASM, make a GET request to the root namespace, (/mgmt/tm/asm), as
shown in this example.
GET https://192.168.25.42/mgmt/tm/asm
{
"selfLink":"https://localhost/mgmt/tm/asm",
"kind":"tm:asm:asmcollectionstate",
"items":[
{
"reference":{
"link":"https://localhost/mgmt/tm/asm/tasks"
}
},
{
"reference":{
"link":"https://localhost/mgmt/tm/asm/signature-update"
}
},
{
"reference":{
"link":"https://localhost/mgmt/tm/asm/policies"
}
},
{
"reference":{
"link":"https://localhost/mgmt/tm/asm/policy-templates"
}
},
{
"reference":{
"link":"https://localhost/mgmt/tm/asm/signatures"
}
},
{
"reference":{
"link":"https://localhost/mgmt/tm/asm/signature-statuses"
}
},
69
iControl®REST API User Guide
{
"reference":{
"link":"https://localhost/mgmt/tm/asm/signature-sets"
}
},
{
"reference":{
"link":"https://localhost/mgmt/tm/asm/signature-systems"
}
},
{
"reference":{
"link":"https://localhost/mgmt/tm/asm/attack-types"
}
}
]
}
3. To expand one of the links in the response, make another GET request, specically for a resource.
This example expands one of the links in the response from the previous request. Note that each URI
contains a hash string as a resource identier.
GET https://192.168.25.42/mgmt/tm/asm/policies
{
"selfLink":"https://localhost/mgmt/tm/asm/policies",
"kind":"tm:asm:policies:policycollectionstate",
"items":[
{
"policyBuilderReference":{
"link":"https://../mgmt/tm/asm/policies/MwavowFbOsSD-Fgt4trP6A/policy-builder"
},
"blockingSettingReference":{
"link":"https://../mgmt/tm/asm/policies/MwavowFbOsSD-Fgt4trP6A/blocking-settings",
"isSubCollection":true
},
"cookieReference":{
"link":"https://../mgmt/tm/asm/policies/MwavowFbOsSD-Fgt4trP6A/cookies",
"isSubCollection":true
},
"hostNameReference":{
"link":"https://../mgmt/tm/asm/policies/MwavowFbOsSD-Fgt4trP6A/host-names",
"isSubCollection":true
},
"selfLink":"https://../mgmt/tm/asm/policies/MwavowFbOsSD-Fgt4trP6A",
"stagingSettings":{
"signatureStaging":true,
"enforcementReadinessPeriod":7
},
"versionDeviceName":"10000-1-E12U39.sh",
"signatureReference":{
"link":"https://../mgmt/tm/asm/policies/MwavowFbOsSD-Fgt4trP6A/signatures",
"isSubCollection":true
},
"createdDatetime":"2013-12-06T19:29:54Z",
"filetypeReference":{
70
Application Security Manager
"link":"https://../mgmt/tm/asm/policies/MwavowFbOsSD-Fgt4trP6A/filetypes",
"isSubCollection":true
},
"id":"MwavowFbOsSD-Fgt4trP6A",
"modifierName":"admin",
"versionDatetime":"2013-12-26T23:12:57Z",
"subPath":"/Common",
"versionLastChange":"Policy Attributes [update]: Policy Builder
determined that security policy \"/Common/my-VS\" is unstable.",
"active":true,
"caseInsensitive":false,
"name":"my-VS",
"description":"",
"fullPath":"/Common/my-VS",
"policyBuilderEnabled":true,
"trustXff":false,
"partition":"Common",
"attributes":{
"pathParameterHandling":"as-parameters",
"triggerAsmIruleEvent":"disabled",
"maskCreditCardNumbersInRequest":true,
"inspectHttpUploads":false,
"maximumHttpHeaderLength":2048,
"maximumCookieHeaderLength":2048,
"useDynamicSessionIdInUrl":false
},
"xmlProfileReference":{
"link":"https://../mgmt/tm/asm/policies/MwavowFbOsSD-Fgt4trP6A/xml-profiles",
"isSubCollection":true
},
"methodReference":{
"link":"https://../mgmt/tm/asm/policies/MwavowFbOsSD-Fgt4trP6A/methods",
"isSubCollection":true
},
"customXffHeaders":[
],
"creatorName":"admin",
"kind":"tm:asm:policies:policystate",
"urlReference":{
"link":"https://../mgmt/tm/asm/policies/MwavowFbOsSD-Fgt4trP6A/urls",
"isSubCollection":true
},
"virtualServers":[
"/Common/my-VS"
],
"headerReference":{
"link":"https://../mgmt/tm/asm/policies/MwavowFbOsSD-Fgt4trP6A/headers",
"isSubCollection":true
},
"protocolIndependent":false,
"lastUpdateMicros":1.386358822e+15,
"signatureSetReference":{
"link":"https://../mgmt/tm/asm/policies/MwavowFbOsSD-Fgt4trP6A/signature-sets",
"isSubCollection":true
},
"allowedResponseCodes":[
400,
401,
404,
407,
71
iControl®REST API User Guide
417,
503
],
"parameterReference":{
"link":"https://../mgmt/tm/asm/policies/MwavowFbOsSD-Fgt4trP6A/parameters",
"isSubCollection":true
},
"jsonProfileReference":{
"link":"https://../mgmt/tm/asm/policies/MwavowFbOsSD-Fgt4trP6A/json-profiles",
"isSubCollection":true
},
"applicationLanguage":"utf-8",
"enforcementMode":"transparent",
"isModified":false,
"gwtProfileReference":{
"link":"https://../mgmt/tm/asm/policies/MwavowFbOsSD-Fgt4trP6A/gwt-profiles",
"isSubCollection":true
},
"whitelistIpReference":{
"link":"https://../mgmt/tm/asm/policies/MwavowFbOsSD-Fgt4trP6A/whitelist-ips",
"isSubCollection":true
},
"versionPolicyName":"/Common/Dummy-VS"
}
]
}
4. To search for properties of a resource, make a GET request and append a query string to the URI, as
shown in this example.
GET https://192.168.25.42/mgmt/tm/asm/policies?$filter=name eq my-VS
Creating Application Security Manager resources
Consistent with iControl®REST behavior, Application Security Manager™(ASM™) supports creation of
resources within the namespace /mgmt/tm/asm. As with any other organizing collection in iControl®
REST, you can make a POST request to create a resource in ASM.
To create a new resource, make a POST request using the namespace /mgmt/tm/asm.
POST https://192.168.25.42/mgmt/tm/asm/policies/<MD5HASH>/urls
{
"name": "/login.php",
"protocol": "http",
72
Application Security Manager
"description": "A Login Page"
}
{
"id": "<MD5HASH>",
"name": "/login.php",
"kind": "tm:asm:policies:urls:urlState",
"selfLink":
"https://localhost/mgmt/tm/asm/policies/<MD5HASH>/urls/XPiqHHfl7UsVKku63zrd-g",
"protocol": "http",
"type": "explicit",
"staging": true,
"description": "A Login Page",
"modifiedDatetime": "1990-12-31T23:59:60Z",
"allowed": true,
"checkFlow": false,
"navigationParameters": false,
"checkMetachars": true,
"clickjackingProtection": false,
"contentProfiles: [
{
"headerName": "*",
"headerValue": "*",
"headerOrder": "default",
"type": "http",
"inClassification": false
}
]
"parameterReference": {
"link":
"https://localhost/mgmt/tm/asm/policies/<MD5HASH>/urls/XPiqHHfl7UsVKku63zrd-g/parameters"
},
}
Updating Application Security Manager resources
Consistent with iControl®REST behavior, Application Security Manager™(ASM™) supports updating of
resources within the namespace /mgmt/tm/asm. As with any other resources in iControl®REST, you can
update an ASM collection or other resource with a PATCH request.
1. To update a resource, make a PATCH request to a resource in the namespace /mgmt/tm/asm and
include a JSON body.
PATCH https://192.168.25.42/mgmt/tm/asm/policies/<MD5HASH>/urls/
{
"clickjackingProtection": true,
"clickjackingtype":"Never"
}
2. To update multiple ASM entities with a single request, make a PATCH request and specify a query
parameter in the URI.
PATCH https://192.168.25.42/mgmt/tm/asm/policies/<MD5HASH>/urls?$filter=type
eq explicit
73
iControl®REST API User Guide
{ "staging": false }
Deleting resources in Application Security Manager
Consistent with iControl®REST behavior, the namespace for Application Security Manager™(ASM™)
includes endpoints within the namespace /mgmt/tm/asm/tasks/import-policy/. As with any other
resources in iControl REST, you can make a DELETE request to delete a resource in ASM.
1. To delete a resource, make a DELETE request and specify a resource in the namespace
/mgmt/tm/asm/tasks/import-policy/.
DELETE
https://192.168.25.42/mgmt/tm/asm/tasks/import-policy/ZuJ5QPuFj9r_LwbrDgoPsg
{
"isBase64":false,
"status":"FAILURE",
"name":"TCB policy",
"lastUpdateMicros":1.389135008e+15,
"kind":"tm:asm:tasks:import-policy:import-policy-taskstate",
"selfLink":"https://../mgmt/tm/asm/tasks/import-policy/ZuJ5QPuFj9r_LwbrDgoPsg",
"filename":"tcbpolicy.xml",
"id":"ZuJ5QPuFj9r_LwbrDgoPsg",
"startTime":"2014-01-07T22:50:08Z",
"result":{
"message":"Exported policy file not found!."
}
}
2. To delete multiple entities, make a DELETE request and specify a query parameter in the URI.
DELETE
https://192.168.25.42/mgmt/tm/asm/policies/<MD5HASH>/urls/?$filter=staging
eq true
Application Security Manager policy
If you use Application Security Manager™(ASM™) to import, export, or activate policy, you should
understand how ASM differs from iControl REST.
iControl®REST supports the Application Security Manager™(ASM™) features of importing, exporting,
and activating policies. The individual task topics state all required properties for a request.
DescriptionProperty
Species the name of a local system le that contains the policy to import.filename
74
Application Security Manager
DescriptionProperty
Species inline content in XML format to import. For import requests, the
inline content is input. For export requests, the response contains the content
inline.
file
Indicates whether the inline content is Base64 encoded. Applies to both
input and output content.
isBase64
Indicates whether to export only custom settings.minimal
Species the short name of a policy. Only applies to new policies.name
Species the fully qualied path and name of a policy.fullPath
Species the link to a policy to activate, replace or create, or export.policyReference
Species the template for a policy.policyTemplateReference
Importing a policy in Application Security Manager
iControl®REST supports the Application Security Manager™(ASM™) task to import a policy from another
ASM system. You can use the imported policy as a base policy on another system.
1. (Optional) To upload a le from which to import the policy, use the POST method and specify the
/tm/asm/file-transfer/uploads endpoint. You must specify the le name in the request.
POST https://192.168.25.42/mgmt/tm/asm/file-transfer/uploads/<filename>
2. To import a policy, make a POST request to the /mgmt/tm/asm/tasks/import-policy namespace.
3. In the JSON body, specify a property that identies the source of the import data.
You must supply one property from the list:
•file
•filename
•policyReferenceTemplate
POST https://192.168.25.42/mgmt/tm/asm/tasks/import-policy
{
"filename": "mypolicy.xml",
"name": "NewPolicy"
}
{
"id": "oqNah2PxtwwE4YyAHGekNQ",
"name": "NewPolicy",
"filename": "mypolicy.xml"
"kind": "tm:asm:tasks:import-policy:importpolicytaskstate",
"lastUpdateMicros": 1370459676272126,
"status": "NEW",
"selfLink":
"https://localhost/mgmt/tm/asm/tasks/import-policy/oqNah2PxtwwE4YyAHGekNQ",
"startTime": "2013-06-05T15:14:36-04:00"
}
75
iControl®REST API User Guide
4. Make a GET request and specify the id property in the URI to determine the success of the policy import
operation.
The response shows the result and status properties that indicate the success of the request.
GET
https://192.168.25.42/mgmt/tm/asm/tasks/import-policy/oqNah2PxtwwE4YyAHGekNQ
{
"id": "oqNah2PxtwwE4YyAHGekNQ",
"kind": "tm:asm:tasks:import-policy:importpolicytaskstate",
"name": "NewPolicy",
"filename": "mypolicy.xml"
"lastUpdateMicros": 1370459676272126,
"status": "COMPLETED",
"selfLink":
"https://localhost/mgmt/tm/asm/tasks/import-policy/oqNah2PxtwwE4YyAHGekNQ",
"startTime": "2013-06-05T15:14:36-04:00",
"endTime": "2013-06-05T15:14:56-04:00",
"result": {
"policyReference": {
"link":
"https://localhost/mgmt/tm/asm/policies/vagoQLF6uOoBKvS8h3C19w"
}
}
}
Exporting a policy in Application Security Manager
iControl®REST supports the Application Security Manager™(ASM™) task for exporting a policy to another
server. You can use the exported policy as a base policy on another system.
1. To export a policy, make a POST request to the /mgmt/tm/asm/tasks/export-policy endpoint.
You must specify either the filename property or the inline property in the request.
POST https://192.168.25.42/mgmt/tm/asm/tasks/export-policy
{
"filename": "exported_file.xml",
"minimal": true,
"policyReference": {
"link":
"https://localhost/mgmt/tm/asm/policies/vagoQLF6uOoBKvS8h3C19w"
}
}
The response to the request contains the following data:
{
"id": "oqNah2PxtwwE4YyAHGekNQ",
"filename": "exported_file.xml",
"policyReference": {
"link":
"https://localhost/mgmt/tm/asm/policies/vagoQLF6uOoBKvS8h3C19w"
},
"minimal": true,
"kind": "tm:asm:tasks:export-policy:exportpolicytaskstate",
"lastUpdateMicros": 1370459676272126,
"status": "NEW",
76
Application Security Manager
"selfLink":
"https://localhost/mgmt/tm/asm/tasks/export-policy/oqNah2PxtwwE4YyAHGekNQ",
"startTime": "2013-06-05T15:14:36-04:00"
}
2. (Optional) To determine the status of the policy export operation, use the GET method and specify the
id of the request.
GET
https://192.168.25.42/mgmt/tm/asm/tasks/export-policy/oqNah2PxtwwE4YyAHGekNQ
The response to the request contains the following data:
{
"id": "oqNah2PxtwwE4YyAHGekNQ",
"filename": "exported_file.xml",
"policyReference": {
"link":
"https://localhost/mgmt/tm/asm/policies/vagoQLF6uOoBKvS8h3C19w"
},
"minimal": true,
"kind": "tm:asm:tasks:export-policy:exportpolicytaskstate",
"lastUpdateMicros": 1370459676272126,
"status": "COMPLETED",
"selfLink":
"https://localhost/mgmt/tm/asm/tasks/export-policy/oqNah2PxtwwE4YyAHGekNQ",
"startTime": "2013-06-05T15:14:36-04:00",
"endTime": "2013-06-05T15:14:56-04:00",
"result": {
"filename": "exported_file.xml",
"fileSize": 32045
}
}
3. (Optional) To download the le, use the GET method and specify the
/tm/asm/file-transfer/downloads endpoint, along with the name of the exported le. You must
specify the name of the le in the request.
GET https://192.168.25.42/mgmt/tm/asm/file-transfer/downloads/<filename>
Applying a policy in Application Security Manager
iControl®REST supports the Application Security Manager™(ASM™) task to manually apply a policy that
protects a web site.
1. To apply a policy, make a POST request with the /tm/asm/tasks/apply-policy namespace.
POST https://192.168.25.42/mgmt/tm/asm/tasks/apply-policy
{
"policyReference": {
"link":
"https://localhost/mgmt/tm/asm/policies/vagoQLF6uOoBKvS8h3C19w"
77
iControl®REST API User Guide
}
}
The response to the request contains the following data:
{
"id": "oqNah2PxtwwE4YyAHGekNQ",
"kind": "tm:asm:tasks:apply-policy:applypolicytaskstate",
"policyReference": {
"link":
"https://localhost/mgmt/tm/asm/policies/vagoQLF6uOoBKvS8h3C19w"
},
"lastUpdateMicros": 1370459678272126,
"status": "NEW",
"selfLink":
"https://localhost/mgmt/tm/asm/tasks/apply-policy/oqNah2PxtwwE4YyAHGekNQ",
"startTime": "2013-06-05T15:14:36-04:00"
}
2. To determine the status of the apply policy operation, make a GET request to the same namespace.
GET https://192.168.25.42/mgmt/tm/asm/tasks/apply-policy
The response to the request contains the following data:.
{
"id": "oqNah2PxtwwE4YyAHGekNQ",
"kind": "tm:asm:tasks:apply-policy:applypolicytaskstate",
"policyReference": {
"link":
"https://localhost/mgmt/tm/asm/policies/vagoQLF6uOoBKvS8h3C19w"
},
"lastUpdateMicros": 1370459678272126,
"status": "COMPLETED",
"selfLink":
"https://localhost/mgmt/tm/asm/tasks/apply-policy/oqNah2PxtwwE4YyAHGekNQ",
"startTime": "2013-06-05T15:14:36-04:00",
"endTime": "2013-06-05T15:14:56-04:00"
}
Application Security Manager signatures
If you use Application Security Manager™(ASM™) to manage signatures, you should understand how ASM
differs from iControl REST.
iControl®REST supports the Application Security Manager™(ASM™) features to check, export, or update
signatures.
DescriptionProperty
Species inline imported or exported content in XML format.file
Indicates whether the exported signatures are contained inline in the response.inline
Indicates whether the inline content is Base64 encoded, either input or output.
If inline is set to TRUE, the exported signatures are Base64 encoded.
isBase64
Species the name of a local signature le.filename
78
Application Security Manager
DescriptionProperty
Indicates whether a signature is considered to be a user-dened signature.isUserDefined
Checking for signatures in Application Security Manager
iControl®REST supports the Application Security Manager™(ASM™) task to check signatures for updates
to the signature les.
1. To check for new signatures, make a POST request to the /tm/asm/tasks/check-signatures
namespace, and include an empty JSON body ({ }).
POST https://192.168.25.42/mgmt/tm/asm/tasks/check-signatures
{
"id": "oqNah2PxtwwE4YyAHGekNQ",
"kind": "tm:asm:tasks:check-signatures:check-signaturestaskstate",
"lastUpdateMicros": 1370459676272126,
"status": "NEW",
"selfLink":
"https://localhost/mgmt/tm/asm/tasks/check-signatures/oqNah2PxtwwE4YyAHGekNQ",
"startTime": "2013-06-05T15:14:36-04:00"
}
2. To determine the status of the check for new signatures operation, make a GET request.
GET
https://192.168.25.42/mgmt/tm/asm/tasks/check-signatures/oqNah2PxtwwE4YyAHGekNQ
The response to the request contains the following data:
{
"id": "oqNah2PxtwwE4YyAHGekNQ",
"kind": "tm:asm:tasks:check-signatures:check-signaturestaskstate",
"lastUpdateMicros": 1370459676272126,
"status": "NEW",
"selfLink":
"https://localhost/mgmt/tm/asm/tasks/check-signatures/oqNah2PxtwwE4YyAHGekNQ",
"startTime": "2013-06-05T15:14:36-04:00",
"endTime": "2013-06-05T15:14:56-04:00",
"result": {
"updatesAvailable": false
}
}
Updating signatures in Application Security Manager
iControl®REST supports the Application Security Manager™(ASM™) task to update signatures.
79
iControl®REST API User Guide
1. (Optional) To upload a le from which to update the signatures, use the POST method and specify the
/tm/asm/file-transfer/uploads endpoint. You must specify the name of the le in the request.
POST https://192.168.25.42/mgmt/tm/asm/file-transfer/uploads/<filename>
2. To update signatures, make a POST request to the /tm/asm/tasks/update-signatures namespace
and include an empty JSON body ({ }).
POST https://192.168.25.42/mgmt/tm/asm/tasks/update-signatures
{}
{
"id": "oqNah2PxtwwE4YyAHGekNQ",
"kind": "tm:asm:tasks:update-signatures:update-signaturestaskstate",
"lastUpdateMicros": 1370459676272126,
"status": "NEW",
"selfLink":
"https://localhost/mgmt/tm/asm/tasks/update-signatures/oqNah2PxtwwE4YyAHGekNQ",
"startTime": "2013-06-05T15:14:36-04:00"
}
3. To determine the status of the update signatures operation, make a GET request.
GET
https://192.168.25.42/mgmt/tm/asm/tasks/update-signatures/oqNah2PxtwwE4YyAHGekNQ
The response contains the results of the task.
{
"id": "oqNah2PxtwwE4YyAHGekNQ",
"kind": "tm:asm:tasks:update-signatures:update-signaturestaskstate",
"lastUpdateMicros": 1370459676272126,
"status": "COMPLETED",
"selfLink":
"https://localhost/mgmt/tm/asm/tasks/update-signatures/oqNah2PxtwwE4YyAHGekNQ",
"startTime": "2013-06-05T15:14:36-04:00",
"endTime": "2013-06-05T15:14:56-04:00",
"result": {
"signatureStatusReference": {
"link":
"https://localhost/mgmt/tm/asm/signature_statuses/vagoQLF6uOoBKvS8h3C19w"
}
}
}
Exporting signatures in Application Security Manager
iControl®REST supports the Application Security Manager™(ASM™) task to export signatures for use on
another ASM system.
80
Application Security Manager
1. To export signatures, make a POST request to the /tm/asm/tasks/export-signatures namespace,
and specify the name of the output le in the JSON body.
POST https://192.168.25.42//mgmt/tm/asm/tasks/export-signatures
{
"filename": "exported_file.xml",
}
{
"id": "oqNah2PxtwwE4YyAHGekNQ",
"filename": "exported_file.xml",
"kind": "tm:asm:tasks:export-signatures:exportsignaturestaskstate",
"lastUpdateMicros": 1370459676272126,
"status": "NEW",
"selfLink":
"https://localhost/mgmt/tm/asm/tasks/export-signatures/oqNah2PxtwwE4YyAHGekNQ",
"startTime": "2013-06-05T15:14:36-04:00"
}
2. (Optional) To determine the status of the export signatures operation, make a GET request.
GET
https://192.168.25.42/mgmt/tm/asm/tasks/export-signatures/oqNah2PxtwwE4YyAHGekNQ
{
"id": "oqNah2PxtwwE4YyAHGekNQ",
"filename": "exported_file.xml",
"kind": "tm:asm:tasks:export-signatures:exportsignaturestaskstate",
"lastUpdateMicros": 1370459676272126,
"status": "COMPLETED",
"selfLink":
"https://localhost/mgmt/tm/asm/tasks/export-signatures/oqNah2PxtwwE4YyAHGekNQ",
"startTime": "2013-06-05T15:14:36-04:00",
"endTime": "2013-06-05T15:14:56-04:00",
"result": {
"filename": "exported_file.xml",
}
}
3. (Optional) To download the le, use the GET method and specify the
/tm/asm/file-transfer/downloads endpoint, along with the name of the exported le. You must
specify the name of the le in the request.
GET https://192.168.25.42/mgmt/tm/asm/file-tranfer/downloads/exported_file.xml
Retrieving signature status information in Application Security Manager
iControl®REST supports the Application Security Manager™(ASM™) feature to retrieve signature status
information for a signature. Signature status includes information regarding additions and deletions to a
signature le.
81
iControl®REST API User Guide
To retrieve signature status information, make a GET request to the /tm/asm/signature-statuses
namespace.
GET https://192.168.25.42/mgmt/tm/asm/signature-statuses/<MD5HASH>
The items property shows the signature status.
{
"selfLink": "https://localhost/mgmt/tm/asm/signature-statuses",
"kind": "tm:asm:signature-statuses:signature-statuscollectionstate",
"items": [
{
"sigsAdded": 0,
"isUserDefined": false,
"readme": "Attack Signature Database packaged with version
11.5.0\n\n\ .... ",
"sigsUpdatedMinor": 0,
"sigsDeleted": 0,
"modifiedSignatures": [],
"loadTime": "2013-10-10T06:43:30Z",
"sigsTotal": 0,
"sigsUpdated": 0,
"selfLink":
"https://localhost/mgmt/tm/asm/signature-statuses/cHzbviRdfEv6l_RRieAdqw",
"kind": "tm:asm:signature-statuses:signature-statusstate",
"timestamp": "2013-10-08T09:06:15Z",
"sigsUpdatedMajor": 0,
"id": "cHzbviRdfEv6l_RRieAdqw"
}
]
}
Retrieving signature systems in Application Security Manager
iControl®REST supports the Application Security Manager™(ASM™) feature to retrieve a signature system.
You must supply the MD5 hash of a signature system to retrieve.
To retrieve signature system information, make a GET request with the /tm/asm/signature-systems
namespace.
GET https://192.168.25.42/mgmt/tm/asm/signature-systems/MD5HASH
The response displays the signature system information, as a link to the resource.
{
"selfLink":
"https://localhost/mgmt/tm/asm/signature-systems/EStDgGiP9nSPgKBhSlDyvQ",
"kind": "tm:asm:signature-systems:signature-systemstate",
"name": "General Database",
"id": "EStDgGiP9nSPgKBhSlDyvQ"
}
82
Application Security Manager
Application Security Manager schema upload
If you use Application Security Manager™(ASM™) to manage schemas, you should understand how iControl®
REST supports schema upload tasks.
iControl®REST provides an endpoint for XML schema le uploads. Application Security Manager™
(ASM™) validates incoming data by using schema les that you upload and then associate to a policy.
DescriptionProperty
Species the name of the XML schema le.fileName
Species the le contents as XML.contents
Uploading schema files in Application Security Manager
Associating an XML schema le to a prole necessitates the ability to upload XML schema les. After
you upload the schema le, you can run a separate task to associate the validation le to the prole.
To upload the XML schema le, use the POST method and specify a policy within the
/tm/asm/policies namespace.
POST
https://192.168.25.42/mgmt/tm/asm/policies/xpqbO1mYOtgfv13j1khKeA/xml-validation-files
{
"fileName": "softwareupdate.wsdl",
"contents": "<validation></validation>"
}
{
"selfLink":
"https://localhost/mgmt/tm/asm/policies/xpqbO1mYOtgfv13j1khKeA/xml-validation-files/d7loGosItLc_ODXuPz83Uw",
"kind":
"tm:asm:policies:xml-validation-files:xml-validation-filestate",
"fileName": "softwareupdate.wsdl",
"contents": "<begin></begin>",
"lastUpdateMicros": 1393332020000000,
"id": "d7loGosItLc_ODXuPz83Uw",
"isReferenced": false
}
Application Security Manager policy restore
If you use Application Security Manager™(ASM™) to restore policy, you should understand how iControl®
REST implements ASM.
iControl®REST supports the Application Security Manager™(ASM™) feature to restore policy based on
policy history. When you restore a policy revision, you must include the policyHistoryRevision
property in the body of a request, and specify the policy revision from which to restore. If you provide a
policyReference property or name property in the body of the request, the task overwrites the policy.
Otherwise, the task creates a new policy.
83
iControl®REST API User Guide
DescriptionProperty
Species the link of the history revision to restore.policyHistoryRevision
Restoring policy revisions in Application Security Manager
The policyHistoryReference property in Application Security Manager™(ASM™) enables a task to
restore a policy revision. The task overwrites the policy if the JSON body contains a policyReference
or name property. Otherwise, the task creates a new policy.
1. To restore a policy revision, use the POST method with the /tm/asm/task/import-policy namespace.
POST https://192.168.25.42/mgmt/tm/asm/tasks/import-policy
{
"policyHistoryReference": {
"link":
"https://localhost/mgmt/tm/asm/policies/vagoQLF6uOoBKvS8h3C19w/history-revisions/hGKdiXU7US4S4qtgexijUQ"
},
"policyReference": {
"link": "https://localhost/mgmt/tm/asm/policies/vagoQLF6uOoBKvS8h3C19w"
}
}
{
"id": "oqNah2PxtwwE4YyAHGekNQ",
"kind": "tm:asm:tasks:import-policy:importpolicytaskstate",
"policyHistoryReference": {
"link":
"https://localhost/mgmt/tm/asm/policies/vagoQLF6uOoBKvS8h3C19w/history-revisions/hGKdiXU7US4S4qtgexijUQ"
},
"policyReference": {
"link":
"https://localhost/mgmt/tm/asm/policies/vagoQLF6uOoBKvS8h3C19w"
},
"lastUpdateMicros": 1370459676272126,
"status": "NEW",
"selfLink":
"https://localhost/mgmt/tm/asm/tasks/import-policy/oqNah2PxtwwE4YyAHGekNQ",
"startTime": "2013-06-05T15:14:36-04:00"
}
2. To check the status of the request, make a GET request with the /tm/asm/task/import-policy
namespace and append the id property from the previous response.
GET
https://192.168.25.42/mgmt/tm/asm/tasks/import-policy/oqNah2PxtwwE4YyAHGekNQ
The response displays the status property for the request.
{
"id": "oqNah2PxtwwE4YyAHGekNQ",
"kind": "tm:asm:tasks:import-policy:importpolicytaskstate",
"lastUpdateMicros": 1370459676272126,
84
Application Security Manager
"policyHistoryReference": {
"link":
"https://localhost/mgmt/tm/asm/policies/vagoQLF6uOoBKvS8h3C19w/history-revisions/hGKdiXU7US4S4qtgexijUQ"
},
"policyReference": {
"link":
"https://localhost/mgmt/tm/asm/policies/vagoQLF6uOoBKvS8h3C19w"
},
"status": "COMPLETED",
"selfLink":
"https://localhost/mgmt/tm/asm/tasks/import-policy/oqNah2PxtwwE4YyAHGekNQ",
"startTime": "2013-06-05T15:14:36-04:00",
"endTime": "2013-06-05T15:14:56-04:00",
"result": {
"policyReference": {
"link":
"https://localhost/mgmt/tm/asm/policies/vagoQLF6uOoBKvS8h3C19w"
}
}
}
Application Security Manager vulnerability import
If you use Application Security Manager™(ASM™) to import vulnerability data, you should understand
how iControl®REST implements ASM.
iControl®REST supports the Application Security Manager™(ASM™) feature to import vulnerabilities
from a le, or to download vulnerabilities from a scanner. You must include the policyReference property
in the JSON body.
DescriptionProperty
Describes the path to the current policy, as a link.policyReference
Species the le contents, in XML format.file
Species the name of the le to read.filename
Indicates whether the le consists of Base64-encoded data.isBase64
Species a scan ID. Required for Cenzic Hailstorm if you do not specify
afile property.
scanId
Species a subscription ID. Required for Cenzic Hailstorm if you do not
specify a file property.
subscriptionId
Indicates whether the task parses the input le and then generates a count
of all vulnerabilities without importing the vulnerabilities.
onlyGetDomainNames
Indicates whether the task parses the input le and imports all
vulnerabilities.
importAllDomainNames
Species the domain names for which the task parses the input le and
imports all vulnerabilities.
domainNames
85
iControl®REST API User Guide
Importing vulnerabilities in Application Security Manager
iControl®REST supports the Application Security Manager™(ASM™) feature to import vulnerability data
from sources, such as les or scanners.
1. To import vulnerabilities, use the POST method with the /tm/asm/tasks/import-vulnerabilities
namespace.
POST https://192.168.25.42/mgmt/tm/asm/tasks/import-vulnerabilities
{
"policyReference": { "link":
"https://localhost/mgmt/tm/asm/policies/xpqbO1mYOtgfv13j1khKeA" },
"importAllDomainNames": false,
"domainNames": [
""
],
"subscriptionId": "4132",
"scanId": "3883"
}
{
"policyReference": { "link":
"https://localhost/mgmt/tm/asm/policies/xpqbO1mYOtgfv13j1khKeA" },
"isBase64": false,
"importAllDomainNames": false,
"status": "NEW",
"lastUpdateMicros": 1395567859000000,
"domainNames": [
""
],
"subscriptionId": "4132",
"scanId": "3883",
"selfLink":
"https://localhost/mgmt/tm/asm/tasks/import-vulnerabilities/8PacFCQc0Umx45mheqdyew",
"kind":
"tm:asm:tasks:import-vulnerabilities:import-vulnerabilities-taskstate",
"id": "8PacFCQc0Umx45mheqdyew",
"startTime": "2014-03-23T09:44:15Z",
"result": {}
}
2. To retrieve the status of the import vulnerability task, use the GET method.
GET
https://192.168.25.42/mgmt/tm/asm/tasks/import-vulnerabilities/8PacFCQc0Umx45mheqdyew
The response to the request contains the following data:
{
"isBase64": false,
"importAllDomainNames": false,
"status": "COMPLETED",
"lastUpdateMicros": 1395567859000000,
"domainNames": [
""
],
"onlyGetDomainNames": false,
"subscriptionId": "4132",
86
Application Security Manager
"scanId": "3883",
"selfLink":
"https://localhost/mgmt/tm/asm/tasks/import-vulnerabilities/8PacFCQc0Umx45mheqdyew",
"kind":
"tm:asm:tasks:import-vulnerabilities:import-vulnerabilities-taskstate",
"policyReference": {
"link":
"https://localhost/mgmt/tm/asm/policies/xpqbO1mYOtgfv13j1khKeA"
},
"id": "8PacFCQc0Umx45mheqdyew",
"startTime": "2014-03-23T09:44:15Z",
"result": {
"vulnerableHosts": [
{
"vulnerabilityCount": "4",
"domainName": ""
},
{
"vulnerabilityCount": "41",
"domainName": "crackme.cenzic.com"
}
]
}
}
Querying vulnerability assessment subscriptions in Application Security Manager
Application Security Manager™(ASM™) supports subscriptions to third-party scanners. You can query
ASM for active vulnerability assessment subscriptions.
Note: ASM only supports subscriptions to Cenzic Hailstorm.
1. To determine the active vulnerability assessment subscriptions, use the POST method with the
/tm/asm/tasks/get-vulnerability-assessment-subscriptions namespace and specify the
policyReference property in the JSON body.
POST
https://192.168.25.42/mgmt/tm/asm/tasks/get-vulnerability-assessment-subscriptions
{
"policyReference": { "link":
"https://localhost/mgmt/tm/asm/policies/xpqbO1mYOtgfv13j1khKeA" }
}
The response shows the request status property that indicates a new request and the id property that
identies the request for other operations.
{
"kind":
"tm:asm:tasks:get-vulnerability-assessment-subscriptions:get-vulnerability-assessment-subscriptions-taskstate",
"selfLink":
"https://localhost/mgmt/tm/asm/tasks/get-vulnerability-assessment-subscriptions/pCOSkFyRGWeAf6Kwcpj38w",
"policyReference": {
"link":
"https://localhost/mgmt/tm/asm/policies/xpqbO1mYOtgfv13j1khKeA"
},
87
iControl®REST API User Guide
"status": "New",
"id": "pCOSkFyRGWeAf6Kwcpj38w",
"startTime": "2014-03-24T09:35:57Z",
"lastUpdateMicros": 1395653765000000,
"result": { }
}
2. To obtain the output of this request, use the GET method with the
/tm/asm/tasks/get-vulnerability-assessment-subscriptions namespace and append the
id property to the URI.
GET
https://192.168.25.42/mgmt/tm/asm/tasks/get-vulnerability-assessment-subscriptions/pCOSkFyRGWeAf6Kwcpj38w
{
"kind":
"tm:asm:tasks:get-vulnerability-assessment-subscriptions:get-vulnerability-assessment-subscriptions-taskstate",
"selfLink":
"https://localhost/mgmt/tm/asm/tasks/get-vulnerability-assessment-subscriptions/pCOSkFyRGWeAf6Kwcpj38w",
"policyReference": {
"link":
"https://localhost/mgmt/tm/asm/policies/xpqbO1mYOtgfv13j1khKeA"
},
"status": "COMPLETED",
"id": "pCOSkFyRGWeAf6Kwcpj38w",
"startTime": "2014-03-24T09:35:57Z",
"lastUpdateMicros": 1395653765000000,
"result": {
"subscriptions": [
{
"scans": [
{
"scanId": "3870",
"completeDateTime": "2013-04-03T08:33:27Z",
"status": "Complete"
},
{
"scanId": "3883",
"completeDateTime": "2013-04-09T08:55:50Z",
"status": "Complete"
}
],
"url":
"http://crackme.cenzic.com/Kelev/register/register.php",
"productId": "F5 Trial Scan",
"subscriptionId": "4132"
}
]
}
}
Initiating vulnerability assessment in Application Security Manager
Vulnerability assessments provide access to third-party scanners, such as Cenzic Hailstorm. The asm/tasks
namespace includes an endpoint to initiate a scan.
88
Application Security Manager
1. To initiate a vulnerability assessment, make a POST request with the
/tm/asm/tasks/initiate-vulnerability-assessment namespace. Include the
policyReference and subscriptionId properties in the JSON body.
POST https://192.168.25.42/mgmt/tm/asm/tasks/initiate-vulnerability-assessment
{
"policyReference": { "link":
"https://localhost/mgmt/tm/asm/policies/xpqbO1mYOtgfv13j1khKeA" },
"subscriptionId": "4132"
}
The response shows the status and id properties of the request.
{
"policyReference": { "link":
"https://localhost/mgmt/tm/asm/policies/xpqbO1mYOtgfv13j1khKeA" },
"status": "NEW",
"lastUpdateMicros": 1395567859000000,
"subscriptionId": "4132",
"selfLink":
"https://localhost/mgmt/tm/asm/tasks/initiate-vulnerability-assessment/8PacFCQc0Umx45mheqdyew",
"kind":
"tm:asm:tasks:initiate-vulnerability-assessment:initiate-vulnerability-assessment-taskstate",
"id": "8PacFCQc0Umx45mheqdyew",
"startTime": "2014-03-23T09:44:15Z",
"result": {}
}
2. To retrieve the status of the initiate vulnerability assessment operation, use the GET method with the
/tm/asm/tasks/initiate-vulnerability-assessment namespace and append the id property
to the URI.
GET
https://192.168.25.42/mgmt/tm/asm/tasks/initiate-vulnerability-assessment/8PacFCQc0Umx45mheqdyew
The response shows the request status and scanId properties.
{
"status": "COMPLETED",
"lastUpdateMicros": 1395567859000000,
"subscriptionId": "4132",
"selfLink":
"https://localhost/mgmt/tm/asm/tasks/initiate-vulnerability-assessment/8PacFCQc0Umx45mheqdyew",
"kind":
"tm:asm:tasks:initiate-vulnerability-assessment:initiate-vulnerability-assessment-taskstate",
"policyReference": {
"link":
"https://localhost/mgmt/tm/asm/policies/xpqbO1mYOtgfv13j1khKeA"
},
"id": "8PacFCQc0Umx45mheqdyew",
"startTime": "2014-03-23T09:44:15Z",
"result": {
"scanId": 4920
}
}
89
iControl®REST API User Guide
Terminating vulnerability assessment in Application Security Manager
Vulnerability assessments provide access to third-party scanners, such as Cenzic Hailstorm. The asm/tasks
namespace includes an endpoint to terminate a scan.
1. To terminate a vulnerability assessment, make a POST request with the
/tm/asm/tasks/terminate-vulnerability-assessment namespace. Include a JSON body with
the policyReference property.
POST
https://192.168.25.42/mgmt/tm/asm/tasks/terminate-vulnerability-assessment
{
"policyReference": { "link":
"https://localhost/mgmt/tm/asm/policies/xpqbO1mYOtgfv13j1khKeA" },
}
The response to the request includes the id that identies the request for a query.
{
"policyReference": { "link":
"https://localhost/mgmt/tm/asm/policies/xpqbO1mYOtgfv13j1khKeA" },
"status": "NEW",
"lastUpdateMicros": 1395567859000000,
"selfLink":
"https://localhost/mgmt/tm/asm/tasks/terminate-vulnerability-assessment/8PacFCQc0Umx45mheqdyew",
"kind":
"tm:asm:tasks:terminate-vulnerability-assessment:terminate-vulnerability-assessment-taskstate",
"id": "8PacFCQc0Umx45mheqdyew",
"startTime": "2014-03-23T09:44:15Z",
"result": {}
}
2. To retrieve the status of the terminate vulnerability assessment operation, use the GET method with the
/tm/asm/tasks/terminate-vulnerability-assessment namespace and append the id property
to the URI.
GET
https://192.168.25.42/mgmt/tm/asm/tasks/terminate-vulnerability-assessment/8PacFCQc0Umx45mheqdyew
The response show the status of request.
{
"status": "COMPLETED",
"lastUpdateMicros": 1395567859000000,
"subscriptionId": "4132",
"selfLink":
"https://localhost/mgmt/tm/asm/tasks/terminate-vulnerability-assessment/8PacFCQc0Umx45mheqdyew",
"kind":
"tm:asm:tasks:terminate-vulnerability-assessment:terminate-vulnerability-assessment-taskstate",
"policyReference": {
"link":
"https://localhost/mgmt/tm/asm/policies/xpqbO1mYOtgfv13j1khKeA"
},
"id": "8PacFCQc0Umx45mheqdyew",
90
Application Security Manager
"startTime": "2014-03-23T09:44:15Z",
"result": {
}
}
Application Security Manager vulnerability resolution
If you use Application Security Manager™(ASM™) for vulnerability resolution, you should understand how
iControl®REST implements ASM.
Application Security Manager™(ASM™) supports options to resolve vulnerabilities, such as staging the
suggested changes for a vulnerability.
DescriptionProperty
Indicates that the task only displays the proposed changes for each
vulnerability but does not implement the change.
getPreResolveMessages
Indicates that the changes made to a policy should be staged.stageVulnerabilities
Species the reference to a vulnerability, as a collection of references.vulnerabilities
Resolving vulnerabilities in Application Security Manager
When you resolve vulnerabilities, Application Security Manager™(ASM™) congures the security policy
to protect a web application against a vulnerability. If you choose, you can stage a vulnerability to allow
more time to test the security policy. Otherwise, ASM applies the changes to the security policy immediately.
1. To resolve the vulnerabilities, use the POST method with the
/tm/asm/tasks/resolve-vulnerabilities namespace, and specify the vulnerabilities
property.
POST https://192.168.25.42/mgmt/tm/asm/tasks/resolve-vulnerabilities
{
"vulnerabilities": [
{"link":
"https://localhost/mgmt/tm/asm/policies/vagoQLF6uOoBKvS8h3C19w/vulnerabilities/abcdef1234567890"},
{"link":
"https://localhost/mgmt/tm/asm/policies/vagoQLF6uOoBKvS8h3C19w/vulnerabilities/qwertytrewqa1234"}
]
}
The response includes the request status and id properties.
{
"id": "oqNah2PxtwwE4YyAHGekNQ",
"vulnerabilities": [
{"link":
"https://localhost/mgmt/tm/asm/policies/vagoQLF6uOoBKvS8h3C19w/vulnerabilities/abcdef1234567890"},
{"link":
"https://localhost/mgmt/tm/asm/policies/vagoQLF6uOoBKvS8h3C19w/vulnerabilities/qwertytrewqa1234"}
91
iControl®REST API User Guide
],
"kind":
"tm:asm:tasks:resolve-vulnerabilities:resolvevulnerabilitiesstate",
"lastUpdateMicros": 1370459676272126,
"status": "NEW",
"selfLink":
"https://localhost/mgmt/tm/asm/tasks/resolve-vulnerabilities/oqNah2PxtwwE4YyAHGekNQ",
"startTime": "2013-06-05T15:14:36-04:00"
}
2. To determine the status of this operation, use the GET method with the
/tm/asm/tasks/resolve-vulnerabilities namespace and append the id property to the URI.
GET
https://192.168.25.42/mgmt/tm/asm/tasks/resolve-vulnerabilities/oqNah2PxtwwE4YyAHGekNQ
The response displays the result property.
{
"id": "oqNah2PxtwwE4YyAHGekNQ",
"vulnerabilities": [
{"link":
"https://localhost/mgmt/tm/asm/policies/vagoQLF6uOoBKvS8h3C19w/vulnerabilities/abcdef1234567890"},
{"link":
"https://localhost/mgmt/tm/asm/policies/vagoQLF6uOoBKvS8h3C19w/vulnerabilities/qwertytrewqa1234"}
],
"kind":
"tm:asm:tasks:resolve-vulnerabilities:resolvevulnerabilitiesstate",
"selfLink":
"https://localhost/mgmt/tm/asm/tasks/resolve-vulnerabilities/oqNah2PxtwwE4YyAHGekNQ",
"lastUpdateMicros": 1370459676272126,
"status": "COMPLETED",
"startTime": "2013-06-05T15:14:36-04:00",
"endTime": "2013-06-05T15:14:56-04:00",
"result": {
"message": "The system does not automatically mitigate the
detection of an SQL injection vulnerability created as a result of a scanner
payload that includes distractive meta characters.\nIn order to mitigate
this vulnerability, manually add the disallowed meta characters to the
vulnerable parameter.\nNote: Characters such as '\"< when injected may change
the SQL query."
}
}
Identifying vulnerabilities in Application Security Manager
iControl®REST supports the Application Security Manager™(ASM™) task to resolve a vulnerability and
obtain the messages that identify a vulnerability, without making changes to the security policy.
92
Application Security Manager
1. To retrieve the pre-resolve messages, use the POST method with the
/tm/asm/tasks/resolve-vulnerabilities namespace, and specify the vulnerabilities and
getPreResolveMessages properties.
POST https://192.168.25.42/mgmt/tm/asm/tasks/resolve-vulnerabilities
{
"vulnerabilities": [
{"link":
"https://localhost/mgmt/tm/asm/policies/vagoQLF6uOoBKvS8h3C19w/vulnerabilities/abcdef1234567890"},
{"link":
"https://localhost/mgmt/tm/asm/policies/vagoQLF6uOoBKvS8h3C19w/vulnerabilities/qwertytrewqa1234"}
],
"getPreResolveMessages": true
}
The response shows the request status and id properties.
{
"id": "oqNah2PxtwwE4YyAHGekNQ",
"vulnerabilities": [
{"link":
"https://localhost/mgmt/tm/asm/policies/vagoQLF6uOoBKvS8h3C19w/vulnerabilities/abcdef1234567890"},
{"link":
"https://localhost/mgmt/tm/asm/policies/vagoQLF6uOoBKvS8h3C19w/vulnerabilities/qwertytrewqa1234"}
],
"getPreResolveMessages": true
"kind":
"tm:asm:tasks:resolve-vulnerabilities:resolvevulnerabilitiesstate",
"lastUpdateMicros": 1370459676272126,
"status": "NEW",
"selfLink":
"https://localhost/mgmt/tm/asm/tasks/resolve-vulnerabilities/oqNah2PxtwwE4YyAHGekNQ",
"startTime": "2013-06-05T15:14:36-04:00"
}
2. To determine the status of this operation, use the GET method with the
/tm/asm/tasks/resolve-vulnerabilities namespace and append the id property to the URI.
GET
https://192.168.25.42/mgmt/tm/asm/tasks/resolve-vulnerabilities/oqNah2PxtwwE4YyAHGekNQ
The response includes the result property and the text message data.
{
"id": "oqNah2PxtwwE4YyAHGekNQ",
"vulnerabilities": [
{"link":
"https://localhost/mgmt/tm/asm/policies/vagoQLF6uOoBKvS8h3C19w/vulnerabilities/abcdef1234567890"},
{"link":
"https://localhost/mgmt/tm/asm/policies/vagoQLF6uOoBKvS8h3C19w/vulnerabilities/qwertytrewqa1234"}
],
"getPreResolveMessages": true
"kind":
93
iControl®REST API User Guide
"tm:asm:tasks:resolve-vulnerabilities:resolvevulnerabilitiesstate",
"selfLink":
"https://localhost/mgmt/tm/asm/tasks/resolve-vulnerabilities/oqNah2PxtwwE4YyAHGekNQ",
"lastUpdateMicros": 1370459676272126,
"status": "COMPLETED",
"startTime": "2013-06-05T15:14:36-04:00",
"endTime": "2013-06-05T15:14:56-04:00",
"result": {
"message": "The following attack signature sets will be
assigned to the security policy: Cross Site Scripting Signatures, SQL
Injection Signatures\nStaging will be disabled for all signatures of Signature
Set: Cross Site Scripting Signatures, SQL Injection Signatures"
}
}
Web Scraping Configuration settings
If you use Application Security Manager™(ASM™) to manage web scraping conguration settings, you
can use an iControl®REST API to retrieve or modify those settings.
iControl REST exposes properties to congure Session Transactions Anomaly settings. The values described
here conform to the settings you are familiar with if you congure web scraping settings in the Trafc
Management UI (TMUI). The string webScrapingConfiguration identies the top-level member of
this resource object.
DescriptionProperty
Indicates whether the system blocks on a session
transaction anomaly, as a Boolean.
sessionTransactionAnomalyBlock
Indicates whether the system sends an alarm on a session
opening anomaly, as a Boolean.
sessionOpeningAnomalyAlarm
Indicates whether the system sends an alarm on a
suspicious client, as a Boolean.
suspiciousClientsAlarm
Indicates whether the system sends an alarm on a session
transaction anomaly, as a Boolean.
sessionTransactionAnomalyAlarm
Indicates whether the blocks on a suspicious client, as a
Boolean.
suspiciousClientsBlock
Indicates whether the system blocks on a session opening
anomaly, as a Boolean.
sessionOpeningAnomalyBlock
Indicates whether the system uses persistent storage for
client identication data, as a Boolean.
usePersistentStorage
Indicates whether the system blocks on bot detection, as
a Boolean.
botDetectionBlock
Indicates whether the system uses ngerprinting to collect
browser attributes, as a Boolean.
useFingerprint
Indicates whether the system sends an alarm on bot
detection, as a Boolean.
botDetectionAlarm
94
Application Security Manager
Session Transactions Anomaly settings
If you use Application Security Manager™(ASM™) to manage web scraping conguration settings, you
can use an iControl®REST API to retrieve and modify those settings.
iControl REST exposes properties to congure Session Transactions Anomaly settings. The values described
in this topic conform to the settings you are familiar with if you congure web scraping settings in the
Trafc Management UI (TMUI). The string sessionTransactionsAnomaly identies the top-level
member of this resource object.
DescriptionProperty
Species that the system considers trafc to be an attack
if the number of transactions per session is equal to or
greater than this number. The default value is 400.
maximumSessionTransactionsPerSecond
Species that the system considers trafc to be an attack
if the number of transactions per session is equal to or
minimumSessionsTransactionsPerSecond
greater than this number, and either the session
transactions increased by value or session transactions
reached value was reached. If the number of transactions
per session is less than this value, the system does not
consider the trafc to be an attack, even if one of the
session transactions increased by value or session
transactions reached value was reached. The default value
is 200.
Species the length of time, in seconds, that the system
prevents a session anomaly attack after the system detects
preventionDuration
and stops an attack, unless the system detects the end of
the attack earlier. The system prevents attacks by blocking
requests. The default value is 1800.
Species that the system considers trafc to be an attack
if the number of transactions in the session is greater than
sessionTransactionsPerSecondIncreaseRate
normal by this percent. Normal is dened as the average
number of transactions per session for the whole site
during the last hour. The default value is 500.
Bot Detection settings
If you use Application Security Manager™(ASM™) to manage web scraping conguration settings, you
can use an iControl®REST API to retrieve and modify those settings.
iControl®REST exposes properties to congure Bot Detection settings. The values described here conform
to the settings you are familiar with if you congure web scraping settings in the Trafc Management UI
(TMUI). The string botDetection identies the top-level member of this resource object.
DescriptionProperty
Species the maximum number of times that one page
can be refreshed within a specied amount of time before
rapidSurfingMaximumDistinctPages
the system considers the client source to be a bot. The
default value is 120.
Species the number of different pages that can be loaded
within a specied amount of time before the system
considers the client source to be a bot.
rapidSurfingMaximumChangedPages
95
iControl®REST API User Guide
DescriptionProperty
Indicates whether the system performs event sequence
enforcement. Conguring this setting protects your web
checkEventsSequenceEnforcement
application against bots by tracking the sequence of events
that the browser triggers to detect irregular sequences.
When an irregular sequence is detected, in order to prevent
false positives, the client is not immediately marked as a
bot. Instead, the client is prevented from being marked
as human until the next web page is loaded.
Species the maximum amount of time that it takes either
to refresh one web page, or to refresh a minimum number
rapidSurfingMaximumTimeDuration
of pages once, in order for the system to suspect that a
bot requested the page. The default value is 30.
Species the number of requests that the system considers
unsafe, thus blocking them if the security policy is in
blockingPeriod
blocking mode. The system did not detect a valid client
during the grace interval, and automatically generates the
Web Scraping Detected violation. In addition, the system
no longer checks these requests for web scraping. After
the client sends the number of requests specied in this
setting, the system reactivates the grace interval. The
default value is 500.
Species the maximum number of requests the system
reviews while trying to detect whether the client is human.
graceThreshold
As soon as the system makes that determination, it stops
checking the requests. The default value is 100. Once the
client determines that the client is valid, the system allows,
and does not check, the next several requests, as specied
by the safe interval setting. If the system does not detect
a valid client during the grace interval, the system issues,
and continues to issue, the Web Scraping Detected
violation until it reaches the number of requests specied
in the blocking period setting.
Species the number of requests that the system considers
safe. The system determined that these requests are sent
safeIntervalThreshold
by a human-backed client and therefore no longer checks
these requests for web scraping. Once the number of
requests sent by the client reaches the value specied in
the setting, the system reactivates the grace interval. The
default value is 2000.
Session Opening Anomaly settings
If you use Application Security Manager™(ASM™) to manage web scraping settings, you can use an
iControl®REST API to retrieve and modify those settings.
iControl®REST exposes properties to congure session opening anomaly settings. The properties described
here conform to the settings you are familiar with if you congure session opening anomaly settings in the
Trafc Management UI (TMUI). The string sessionOpeningAnomaly identies the top-level member
of this resource object.
96
Application Security Manager
DescriptionProperty
Species that the system considers trafc to be an attack
if the number of sessions opened per second is equal to,
minimumSessionsOpenedPerSecond
or greater than, this number, and at least one of the
sessions opened per second increased by or sessions
opened per second reached numbers was reached. If the
number of sessions opened per second is lower than this
number, the system does not consider this trafc to be an
attack even if one of the sessions opened per second
increased by or sessions opened per second reached was
reached. The default value is 25.
Indicates whether the system detects session opening
anomalies by IP address, as a Boolean value.
checkSessionOpeningAnomaly
Indicates whether the system determines if a client is a
legal browser or an illegal script by sending a JavaScript
clientSideIntegrityDefense
challenge to each new session request from the detected
IP address, and waiting for a response. The default value
is false.
Indicates whether the system drops sessions from
suspicious IP addresses after the system determines that
the client is an illegal script. The default value is false.
rateLimiting
Species that the system considers trafc to be an attack
if the number of sessions opened per second is equal to,
or greater than, this number. The default value is 50.
maximumSessionsOpenedPerSecond
Indicates whether the system drops requests from IP
addresses that have a bad reputation according to the
dropIpAddressesWithBadReputation
system's IP address reputation database. Attacking IP
addresses that do not have a bad reputation undergo rate
limiting, as usual. The default value is disabled.
Species that the system considers trafc to be an attack
if the number of sessions opened per second increased by
this number. The default value is 500.
sessionsOpenedPerSecondIncreaseRate
Species the length of time, in seconds, that the system
prevents a session opening anomaly attack after the system
preventionDuration
detects and stops an attack, unless the system detects the
end of the attack earlier. The default value is 1800.
Session Opening Threshold settings
If you use Application Security Manager™(ASM™) to manage web scraping settings, you can use an
iControl®REST API to retrieve and modify those settings.
iControl REST exposes properties to congure session opening threshold settings. The values described
here conform to the settings you are familiar with if you congure session opening threshold settings in the
Trafc Management UI (TMUI). The string sessionOpeningThresholds identies the top-level member
of the resource object.
DescriptionProperty
Indicates whether the system uses ngerprinting to detect
cookie deletion events. Fingerprinting assumes that each
checkFingerprintResets
browser has a unique ngerprint, and therefore the system
97
iControl®REST API User Guide
DescriptionProperty
collects browser attributes to identify browsers and bots.
The default value is false.
Species the length of time, in seconds, that the system
has to detect a specied number of cookie deletion events
openingPersistentStorageResetsDuration
before the system determines a request to be a web
scraping attack and blocks the suspected illegal request.
Species the number of integrity fault events the system
must detect to determine a web scraping attack. The
default value is 3.
openingPersistentStorageInconsistencyEventsMaximum
Species the length of time, in seconds, that the system
prevents a session opening threshold attack after the
preventionDuration
system detects and stops an attack, unless the system
detects the end of the attack earlier. The system prevents
attacks by rejecting requests from the attacking clients.
The system identies the attacking client based on a
unique identication number that was stored in the
attacking browser's persistent storage. The default value
is 1800.
Indicates whether the system blocks requests that it
identies as integrity fault events. The default value is
false.
checkStorageInconsistency
Indicates whether the system uses persistent device
identication to detect cookie deletion events, The default
value is false.
checkStorageResets
Species the number of cookie deletion events that the
system must detect in a specied time period before the
openingPersistentStorageResetsMaximum
system determines an attack to be a web scraping attack
and blocks the suspected illegal request.
Species the length of time, in seconds, that the system
has to detect a specied number of cookie deletion events
fingerprintResetsTimeWindow
before the system determines a request to be a web
scraping attack and blocks the suspected illegal request.
The default value is 600.
Species the length of time, in seconds, that the system
has to detect integrity fault events before the system
openingPersistentStorageInconsistencyEventsDuration
determines an attack to be a web scraping attack. The
default value is 600.
Species the number of cookie deletion events the system
must detect in a specied time period before the system
fingerprintResetsThreshold
determines that a request is a web scraping attack and
blocks the suspected illegal request.
Suspicious Client settings
If you use Application Security Manager™(ASM™) to manage web scraping settings, you can use an
iControl®REST API to retrieve and modify those settings.
98
Application Security Manager
iControl REST exposes properties to congure suspicious client settings. The values described here conform
to the settings you are familiar with if you congure suspicious client settings in the Trafc Management
UI (TMUI). The string suspiciousClients identies the top-level member of the resource object.
DescriptionProperty
Indicates whether the system investigates browsers for
web scraping plug-ins to determine if a client should be
considered suspicious. The default value is false.
detectBrowsersWithScrapingExtensions
Species an array of web scraping extensions that are
considered illegal. If the system determines that a client
is suspicious, it logs and blocks requests from this client.
scrapingExtensions
Species the length of time, in seconds, that the system
prevents requests from a client after the system determines
the client to be suspicious. The default value is 300.
preventionDuration
iControl REST Web Scraping Settings
iControl®REST supports the programmability of Application Security Manager™(ASM™) web scraping
settings. The iControl REST interface provides a single endpoint that supports both query and modication
requests. As a singleton resource, the web scraping resource supports a GET request to retrieve the current
web scraping settings, and a PATCH request to modify resource properties. The PATCH method allows a
partial representation of a resource as the request entity, which means that you only need to specify the
properties you want to change and not the entire resource.
Retrieving web scraping settings
iControl ®REST supports Application Security Manager™(ASM™) functionality by allowing retrieval of
web scraping settings for a BIG-IP®system. You can automate the retrieval of settings from multiple BIG-IP
systems by using the iControl REST API.
To retrieve the web scraping settings, make a GET request to the
/tm/asm/policies/<MDHASH>/web-scraping endpoint.
GET https://192.168.25.42/mgmt/tm/asm/policies/<MDHASH>/web-scraping
iControl REST retrieves the web scraping settings for all trafc patterns.
{
"suspiciousClients":{
"detectBrowsersWithScrapingExtensions":false,
"preventionDuration": 300,
"scrapingExtensions":[]
},
"sessionOpeningThresholds":{
"checkFingerprintResets":true,
"checkStorageInconsistency":true,
"checkStorageResets":true,
"openingPersistentStorageResetsDuration": 707,
"openingPersistentStorageResetsMaximum": 77,
"fingerprintResetsTimeWindow": 607,
"openingPersistentStorageInconsistencyEventsMaximum": 7,
"persistentStorageMaxPreventionDuration": 1807,
"openingPersistentStorageInconsistencyEventsDuration": 677,
"fingerprintResetsThreshold": 17
99
iControl®REST API User Guide
},
"sessionOpeningAnomaly":{
"minimumSessionsOpenedPerSeconds": 22,
"checkSessionOpeningAnomaly":true,
"PreventionDuration": 1802,
"clientSideIntegrityDefense":true,
"rateLimiting":true,
"maximumSessionsOpenedPerSeconds": 52,
"dropIpAddressesWithBadIpReputation":true,
"sessionsOpenedPerSecondsIncressRate": 502
},
"botDetection":{
"rapidSurfingMaximumDistinctPages": 301,
"rapidSurfingMaximumChangedPages": 1201,
"checkEventSequenceEnforcement":true,
"rapidSurfingMaximumTimeDuration": 311,
"unsafeIntervalTreshold": 10011,
"graceTreshold": 1001,
"safeIntervalTreshold": 20001
},
"sessionTransactionsAnomaly":{
"maximumSessionTransactionsPerSecond": 403,
"minimumSessionTransactionsPerSecond": 203,
"maximumTransactionPreventionDuration": 1803,
"sessionTransactionsPerSecondIncreaseRate": 503
},
"webScrapingConfiguration":{
"alarmOnBotDetection":true,
"blockOnSessionTransactionAnomaly":false,
"alarmOnSessionOpeningAnomaly":true,
"alarmOnSuspiciousClients":true,
"alarmOnSessionTransactionAnomaly":true,
"blockOnBotDetection":false,
"blockOnSessionOpeningAnomaly":false,
"usePersistentStorage":true,
"useFingerprint":true,
"blockOnSuspiciousClients":true,
"persistentDataValidityPeriod": 126
},
"selfLink":"https://localhost/mgmt/tm/asm/policies/xpqbO1mYOtgfv13j1khKeA/web-scraping?ver=12.0.0",
"kind":"tm:asm:policies:web-scraping-settings:web-scraping-settingsstate"
}
Modifying web scraping settings
iControl®REST supports Application Security Manager™(ASM™) functionality by enabling modications
to web scraping settings for a BIG-IP®system. You can automate the modication of settings from multiple
BIG-IP systems by using the iControl REST API.
To modify the prevention duration property for session transaction anomalies, make a PATCH request
to the /tm/asm/policies/<MDHASH>/web-scraping endpoint. Specify the top-level member for
the trafc pattern you want to modify and the desired property change in the JSON body. To change
more than one setting for session transaction anomalies, specify multiple properties in the resource
object, separated by commas.
PATCH https://192.168.25.42/mgmt/tm/asm/policies/<MDHASH>/web-scraping
{
"sessionTransactionsAnomaly": { "preventionDuration": 2400 }
}
100
Application Security Manager
The JSON body must include at least one top-level member that identies a trafc pattern, such as
sessionTransactionsAnomaly.
Learning Suggestion Object
If you use Policy Builder functionality in Application Security Manager™(ASM™), the properties in this
table appear as they would in a JSON body, in response to a GET request.
DescriptionProperty
Species a unique identier for a reference.id
Species the creation time for a suggestion, as a date-time
value.
creationDatetime
Species the last time a matching request for a suggestion
occurred.
lastOccurrenceDatetime
Species the learning status of a suggestion. Possible
values are: pending,ignored,accept, or
status
accept-and-stage. The accept-and-stage status
enables the staging ag for the target entity, if applicable,
and implements the changes specied in the
entityChanges eld.
Indicates that a suggestion will be learned manually, as
a Boolean value. If true, a suggestion will never be
learned automatically.
alwaysManual
Species the user's notes on the suggestion.comment
Indicates that a suggestion has been read by a user, as a
Boolean.
isRead
Species an index based on R2 or R3 measurement that
reects the strength of a suggestion.
score
Species the reason for the suggestion. Possible values
are: violation-mitigation or policy-refinement.
triggerType
Species the type of violation that triggered a suggestion,
if the trigger type is violation. This attribute is not
required.
violationReference
Species the changes to apply to an entity or
entityReference if you accept the suggestion.
entityChanges
Species the type of element for a suggestion. This
attribute is not required.
entityKind
Species the name of an item instance. This attribute is
not required.
entityName
Species the suggested operation for an item. Possible
values are: delete,add-or-update,update-append,
or update-remove. This value is not required.
action
Species a reference to a policy if the entity exists in the
policy; otherwise, species the details of the entity to
create.
entity,entityReference
101
iControl®REST API User Guide
DescriptionProperty
Species a reference to a parent policy entity that matched
a wild card value.
parentEntityReference
Species the number of requests that triggered a
suggestion.
occurrenceCount
Species the number of distinct client IP addresses, on a
list of trusted clients, that triggered a suggestion.
trustedIpCount
Species the number of distinct client IP addresses, not
on a list of trusted clients, that triggered a suggestion.
untrustedIpCount
Species the number of distinct client sessions, from
trusted IP addresses, that triggered a suggestion.
trustedSessionCount
Species the number of distinct client sessions, not from
trusted IP addresses, that triggered a suggestion.
untrustedSessionCount
Species a collection of representative requests, from
various IP addresses and sessions, that triggered a
suggestion.
sampleRequests
Species a description of the changes to implement.description
Species a reason for a suggestion for when a type is
policy-refinement rather than
violation-mitigation.
refinement,refinementReference
Species a reference to an attack signature,either as an
override on another object, or to effect a change on the
signature itself, such as disabling the signature.
signatureReference
Species a reference to a metachar, either as an override
on another object, or to modify the metachar itself, such
as allowing the character itself.
metachar
Species the average violation rating for a suggestion, if
applicable.
averageViolationRating
Species the number of violation ratings for each request.violationRatingCounts
About using Policy Builder in iControl REST
Application Security Manager™(ASM™) security policies undergo modication through a framework called
unied learning and policy building. Unied learning and policy building supports both manual and automatic
updates to a security policy. As an administrator, you can retrieve the policy builder suggestions and modify
the policy suggestions using the iControl®REST API. Operations you can perform include ordering
suggestions by scores or types, viewing more details about a suggestion, or viewing details about related
suggestions. iControl REST supports three methods on the /suggestions endpoint: GET, DELETE, and
PATCH. Other than GET requests to view the collection of suggestions, you will probably have cause to
modify the individual suggestions to change the status of a suggestion, add a comment, or mark a suggestion
as read. You can use the HTTP PATCH method to modify the status,comment, or isRead properties.
As an aside, if you modify properties other than those mentioned, iControl REST ignores those properties
in a request. Refer to the Learning Suggestion Object topic for descriptions of the policy builder object.
For more information about policy builder, see the BIG-IP®Application Security Manager (ASM) 12.0
documentation.
102
Application Security Manager
Retrieving Policy Builder suggestions
You can retrieve the suggestions for an Application Security Manager™(ASM™) policy by making a GET
request. By default, ASM retrieves the rst 500 entities.
To retrieve the suggestions for an ASM policy, make a GET request to the /suggestions endpoint
for a specic ASM policy.
GET https://192.168.25.42/mgmt/tm/asm/policies/<MD5HASH>/suggestions
The string abcd1234 in the example represents a hypothetical MD5HASH value for a policy. An actual
MD5 hash value would resemble the following string: d57fb462a2364e494ed824d523acbfcd.
The response includes the suggestions for the policy, up to 1000 entities.
{
"selfLink":"https://localhost/mgmt/tm/asm/policies/abcd1234/suggestions",
"kind":"tm:asm:policies:suggestions:suggestioncollectionstate",
"items":[
{
"id":"123456",
"selfLink":"https://localhost/mgmt/tm/asm/policies/abcd1234/suggestions/123456"
"kind":"tm:asm:policies:suggestions:suggestionstate",
"creationDatetime":"2013-11-21T22:01:21Z",
"lastOccurrenceDatetime":"2013-12-10T21:01:21Z",
"status":"active",
"alwaysManual":false,
"comment":"",
"isRead":false,
"score":76,
"occurrenceCount":378,
"trustedClientIpCount":0,
"trustedSessionCount":0,
"untrustedClientIpCount":4,
"untrustedSessionCount":3,
"triggerType":"violation",
"violationReference":{
"link":"https://localhost/mgmt/tm/asm/violations/ufg0smEkZrpmkoDHfSPGdQ"
},
"parentEntityReference":{
"link":"https://localhost/......."
} "entityReference":{
"link":"https://localhost/......."
},
"entity":{
"kind":"tm:asm:policies:urls:parameterstate",
"name":"foo",
"level":"url",
"url":{
"name":"/foo.php",
"protocol":"http",
}
},
"entityChanges":{
"signatureOverrides":[
{
"signatureReference":{
103
iControl®REST API User Guide
"link":"https://localhost/mgmt/tm/asm/signatures/N64gk_aRPRtaPA4Mt50_LQ"
},
"enabled":false,
},
},
"requestReferences":[
{
"link":"https://localhost/mgmt/tm/asm/events/requests/123000"
},
{
"link":"https://localhost/mgmt/tm/asm/events/requests/123001"
},
{
"link":"https://localhost/mgmt/tm/asm/events/requests/123002"
},
{
"link":"https://localhost/mgmt/tm/asm/events/requests/123003"
},
{
"link":"https://localhost/mgmt/tm/asm/events/requests/123004"
},
{
"link":"https://localhost/mgmt/tm/asm/events/requests/123005"
},
{
"link":"https://localhost/mgmt/tm/asm/events/requests/123006"
},
],
}
]
}
Modifying Policy Builder suggestions
You can modify a suggestion for an Application Security Manager™(ASM™) policy by making a PATCH
request. ASM limits the policy builder properties that you can change.
To modify a suggestion for an ASM policy, make a PATCH request to the /suggestions/<id>
endpoint for a specic ASM policy. This example changes the status to ignored.
PATCH https://192.168.25.42/mgmt/tm/asm/policies/<MD5HASH>/suggestions/465768
{
"status": "ignored"
}
An MD5 hash is a one-way cryptographic hash function. An actual MD5 hash value would resemble
the following string: d57fb462a2364e494ed824d523acbfcd.
104
Application Security Manager
About Device ID
A device identier (Device ID) consists of an opaque string that identies a client application. The stated
purpose of the string is only to identify a client application to a virtual server. Application Security Manager™
(ASM™) features that take advantage of Device ID include brute force login, session awareness, and session
hijacking prevention.
Device identification using fingerprinting
If you use Application Security Manager™(ASM™) to manage device ID settings, you can use an iControl®
REST API to retrieve and modify those settings.
Application Security Manager (ASM) supports device identication using ngerprinting and exposes the
conguration attributes listed in the table. Use the /mgmt/tm/security/dos/profile/application
endpoint.
DescriptionAttribute
Indicates whether to mitigate based on device ID with CS
challenge.
deviceIdClientSideDefense
Indicates whether to mitigate based on device ID with
CAPTCHA challenge.
deviceIdCaptchaChallenge
Indicates whether to mitigate based on device ID with
blocking requests.
deviceIdRateLimiting
Species the mitigation when deviceIdRateLimiting
is enabled, as rate-limit or block-all.
deviceIdRequestBlockingMode
Species the maximum TPS per device ID to arouse
suspicion.
deviceIdMaximumTps
Species the minimum TPS per device ID.deviceIdMinimumTps
Species the percent rate of increase per device ID to
arouse suspicion.
deviceIdTpsIncreaseRate
Application Security Manager (ASM) supports device identication using ngerprinting and exposes the
enabling attributes listed in the table. Use the
/mgmt/tm/asm/policies/<MD5HASH>/brute-force-attack-preventions endpoint.
DescriptionAttributes
Indicate whether to send an alarm, as true or false.
Defaults to true.
alarm
Indicates whether to block the request, as true or false.
Defaults to true.
block
Indicates whether to apply measures to all login pages,
as true or false. The property is available only for the
default brute force protection item. Defaults to false.
bruteForceProtectionForAllLoginPages
Indicates whether to count attempts based on device ID,
as true or false. Defaults to false.
useDeviceId
Species the number of login attempts before blocking.
Defaults to 5.
loginAttemptsFromTheSameClient
105
iControl®REST API User Guide
DescriptionAttributes
Species a value from an enum that sets the duration of
brute force attack prevention, in seconds, or as the string
unlimited.
preventionDuration
Species a period of time during which to measure login
attempts, as seconds. Defaults to 1.
measurementPeriod
Species an identier, as a string.id
Species an interval, in seconds, to wait before
re-enabling the login. Defaults to 600.
reEnableLoginAfter
Species a URL reference.urlReference
Species the detection criteria, as a JSON object,
consisting of
detectionCriteria
failedLoginAttemptsIncreasePercent,
failedLoginAttemptsRateReached, and
minimumFailedLoginAttempts. All values are
integers, and default to 500, 100, 20, respectively.
Species the prevention policy, as a JSON object,
consisting of
preventionPolicy
sourceIpBasedClientSideIntegrityDefense,
sourceIpBasedRateLimiting,
urlBasedClientSideIntegrityDefense, and
urlBasedRateLimiting. All values are Boolean, either
true or false. Defaults to false,true,false, and
true, respectively.
Species the suspicious criteria, as a JSON object,
consisting of
suspiciousCriteria
failedLoginAtttemptsIncreasePercentand
failedLoginAttemptsRateReached. All values are
integers. Default to 500 and 20, respectively.
Enforce method on a URL
If you use Application Security Manager™(ASM™) to manage a per-URL list of allowed or disallowed
methods, you can use an iControl®REST API to modify those settings.
Application Security Manager (ASM) supports a mechanism to dene a per-URL list of allowed or disallowed
methods and exposes the conguration attributes listed in the table. Use the
/mgmt/tm/asm/policies/<MD5HASH>/urls endpoint.
DescriptionAttribute
Indicates whether the override is enabled, as true or
false. Defaults to false.
methodsOverrideOnUrlCheck
Species an array of key-value pairs, in JSON format.
Defaults to true for the allowed property. You must
specify a value for the method property.
methodOverrides
Session awareness mechanisms using fingerprinting
If you use Application Security Manager™(ASM™) to manage session awareness, you can use an iControl®
REST API to retrieve and modify those settings.
106
Application Security Manager
Application Security Manager (ASM) supports session awareness mechanisms using ngerprinting and
exposes the conguration attributes listed in the table. Use the
/mgmt/tm/asm/policies/<MD5HASH>/session-tracking endpoint.
DescriptionAttribute
Indicates whether to manage device ID scope, as true
or false.
checkDeviceIdThreshold
Species the number of violations per device ID scope
when the device ID check is enabled.
deviceIdThreshold
Session hijacking prevention
If you use Application Security Manager™(ASM™) to manage policy settings, you can use an iControl®
REST API to retrieve and modify those settings.
Application Security Manager™(ASM™) mitigates session hijacking by assigning a unique identier to
every client device. By maintaining device ID information for a session, ASM can determine if a session
has been hijacked. Use the /mgmt/tm/asm/policies/<MD5HASH>/session-tracking endpoint.
DescriptionAttribute
Indicates whether session hijacking prevention is enabled
in ASM by policy.
sessionTrackingConguration/enableTrackingSessionHijackingByDeviceId
About WebSockets
The WebSocket protocol denes a bidirectional full-duplex communication channel between a client and
a server within the context of an HTTP connection. A WebSocket connection initiates from an existing
HTTP connection by sending an upgrade header with the value websocket. As part of the handshake
between the client and the server, the server sends 101 Switching Protocols in response. Application
Security Manager™(ASM™) supports a policy for WebSocket security, as a distinct protocol with congurable
attributes. The specication for WebSockets can be found in RFC 6455 - The WebSocket Protocol.
WebSocket protocol
Application Security Manager™(ASM™) supports security policy settings for the WebSocket protocol.
Application Security Manager™(ASM™) supports the WebSocket protocol and exposes the attributes listed
in the table. Use the /mgmt/tm/asm/policies/<MD5HASH>/websocket-urls endpoint.
DescriptionAttribute
Species an identier for the policy.id
Species a name for the policy.name
Indicates whether the name is encoded in Base64 format.
Default is false.
nameBase64Encoded
Species a value from the WebSocket type enum, either
explicit or wildcard.
type
Species an optional description for the WebSocket URL.description
Species the last update time, in microseconds.lastUpdateMicros
Species a value from the enum, either always or never.learnNewEntities
107
iControl®REST API User Guide
DescriptionAttribute
Species a value from the WebSocket protocol enum,
either ws or wss.
protocol
Indicates true for an allowed URL; false for a
disallowed URL.
isAllowed
Indicates whether to check meta-characters in the URL,
as true or false. Defaults to false. Applies only to wild
card URL types.
metaCharsOnWebsocketUrlCheck
Species an array of isAllowed values and
corresponding hexadecimal values that take precedence
metacharOverrides
over the global URL meta-character settings. Defaults to
true and 0x0.
Indicates whether staging is enabled, as true or false.performStaging
Species the matching order of wildcards, as an integer.
Defaults to 0 (zero).
wildcardOrder
Indicates whether to match more than one segment of a
URL for wildcard values, as true or false.
wildcardIncludesSlash
Species the CORS settings, as a JSON object. The object
contains crossDomainAllowedOrigin, a JSON object,
html5CrossOriginRequestsEnforcement
and the enforcementMode property. The
enforcementMode enum values include
remove-all-headers,disabled, and enforce.
Species an action to take on handshake. Enum values
include ignore,block, or remove. Defaults to remove.
extension
Indicates whether to check the message payload, as true
or false.
checkPayload
Indicates whether free formatted text is allowed in the
message payload. Only set if checkPayload is true.
Defaults to true.
allowTextMessage
Indicates whether JSON is allowed in the message
payload. Only set if checkPayload is true. Defaults to
false.
allowJsonMessage
Indicates whether binary content is allowed in the message
payload. Only set if checkPayload is true. Defaults to
false.
allowBinaryMessage
Species a link to a plain text prole for WebSocket
messages. Only set if allowTextMessage is true.
plainTextProle
Species a link to a JSON prole for WebSocket
messages. Only set if allowJsonMessage is true.
jsonProle
Species the maximum binary message size, as an integer.
Defaults to 10000. Only set if allowBinaryMessage is
true.
binaryMessageMaxSize
Species the maximum size of a WebSocket frame, in
bytes.
messageFrameMaxSize
Species the maximum number of message fragments
per frame, as an integer. Defaults to 100.
messageFrameMaxCount
108
Application Security Manager
DescriptionAttribute
Indicates whether to check the maximum specied value,
as true or false. If false, allow any message size.
checkMessageFrameMaxSize
Indicates whether to check the maximum specied value,
as true or false. If false, allow any message size.
checkMessageFrameMaxCount
Indicates whether to check the maximum specied value,
as true or false. If false, allow any message size.
checkBinaryMessageMaxSize
The properties of the crossDomainAllowedOrigin object appear in the following table.
DescriptionAttribute
Indicates whether to include sub-domains, as true or
false. Defaults to false.
includeSubDomains
Species the origin, as a string.originName
Species the origin port number, as an integer. Defaults
to all to specify all ports.
originPort
Species a value from an enum, http,http/https, or
https. Defaults to http/https.
originProtocol
The properties of the jsonProfile object appear in the following table.
DescriptionAttribute
Species a description of the prole, as a string.description
Indicates whether to check for meta-characters, as true
or false.
metacharElementCheck
Indicates whether to check attack signatures, as true or
false.
attackSignatureCheck
Indicates whether the prole is referenced, as true or
false.
isReferenced
Species the defense attributes, as a JSON object.defenseAttributes
Species the sensitive data, as an array of
parameterName strings.
sensitiveData
Species the last update time, in microseconds.lastUpdateMicros
Species metachar overrides, as an array of isAllowed,
as true or false, and metachar, as a hexadecimal
value.
metacharOverrides
Species a name for the prole, as a string.name
Species signature overrides, as an array of enabled, as
true or false, and signatureReference, an object.
signatureOverrides
Species an identier for the prole, as a string.id
The properties of the defenseAttributes object in the jsonProfile appear in the following table.
DescriptionAttribute
Species the length of JSON data, as an integer.maximumTotalLengthOfJSONData
109
iControl®REST API User Guide
DescriptionAttribute
Species the length of a value, as an integer.maximumValueLength
Species the depth of a structure, as an integer.maximimStructureDepth
Species the length of an array, as an integer.maximumArrayLength
Indicates whether to ignore JSON parser warnings, as
true or false.
tolerateJSONParsingWarnings
The properties of the plainTextProfile object appear in the following table.
DescriptionAttribute
Species a description of the prole, as a string.description
Indicates whether to check for meta-characters, as true
or false.
metacharElementCheck
Indicates whether to check attack signatures, as true or
false.
attackSignatureCheck
Indicates whether the prole is referenced, as true or
false.
isReferenced
Species the defense attributes, as a JSON object.defenseAttributes
Species the last update time, in microseconds.lastUpdateMicros
Species metachar overrides, as an array of isAllowed,
as true or false, and metachar, as a hexadecimal
value.
metacharOverrides
Species a name for the prole, as a string.name
Species signature overrides, as an array of enabled, as
true or false, and signatureReference, an object.
signatureOverrides
Species an identier for the prole, as a string.id
The properties of the defenseAttributes object in the plainTextProfile appear in the following
table.
DescriptionAttribute
Species the length of data, as an integer.maximumTotalLength
Species the length of a line, as an integer.maximumLineLength
Indicates whether to do percent decoding, as true or
false.
performPercentDecoding
About AJAX/JSON Login
In addition to HTTP authentication and HTML forms authentication, modern web applications frameworks
use AJAX authentication. A typical AJAX authentication request consists of a POST request of a login
form, with a JSON response. Application Security Manager™(ASM™) supports AJAX login pages.
110
Application Security Manager
AJAX/JSON Authentication
If you use Application Security Manager™(ASM™) to manage AJAX/JSON authentication settings, you
can use an iControl®REST API to retrieve and modify those settings.
Application Security Manager™(ASM™) exposes the properties listed in the table. Use the
/mgmt/tm/asm/policies/<MD5HASH>/login-pages URI as the path to a specic login page resource.
DescriptionAttribute
Species the URL path.urlReference
Species the authentication type for a request, as an enum.
Allowed values include: none,http-basic,ntlm,form,
authenticationType
ajax-or-json-request, or http-digest. For
AJAX/JSON, specify ajax-or-json-request as the
authentication type.
Species the name of the JSON element that corresponds
to the user login.
usernameParameterName
Indicates whether the usernameParameterName
attribute is specied in Base64 encoding.
usernameParameterNameBase64Encoded
Species the name of the JSON element the corresponds
to the user password.
passwordParameterName
Indicates whether the passwordParameterName
attribute is specied in Base64 encoding.
passwordParameterNameBase64Encoded
Indicates whether the login page is referenced elsewhere,
as true or false.
isReferenced
Species an identier for the login page.id
Species the condition to use AJAX/JSON authentication,
as a JSON object. The conditions are name-value pairs,
accessValidation
where the name is: cookieContains,
headerContains,parameterContains,
responseContains,responseHttpStatus, or
responseOmits.
The properties of the accessValidation object are listed in the following table.
DescriptionAttribute
Species a string contained in a cookie.cookieContains
Species a string included as a header.headerContains
Species a string included as a query parameter.parameterContains
Species a string contained in a response.responseContains
Species a string that is not contained in a response.responseOmits
Species a response status, as a string.responseHttpStatus
Indicates whether a query parameter is Base64 encoded.parameterContainsBase64Encoded
Indicates whether a response includes a Base64 encoded
value.
responseContainsBase64Encoded
111
iControl®REST API User Guide
DescriptionAttribute
Indicates whether a response does not include a Base64
encoded value.
responseOmitsBase64Encoded
Application Security Manager (ASM) also exposes the properties of logout pages listed in the following
table. Use the /mgmt/tm/asm/policies/<MD5HASH>/login-enforcement URI as the path to a specic
logout page resource.
DescriptionAttribute
Indicates whether the expiration setting is enabled or
disabled. By default, a session expires after 600 seconds
if no request is received.
expirationTimePeriod
Species authenticated URLs, as an array.authenticatedUrls
Species requestContains, as a string,
urlReference, as a JSON object, and requestOmits,
as a string.
logoutUrls
112
Application Security Manager
Access Policy Manager
About Access Policy Manager
Access Policy Manager®(APM®) provides secure identity and access management for a BIG-IP®system.
iControl®REST exposes the APM endpoints to enable programmatic access to APM resources and the
benets of automation.
APM adheres to the REST principles described previously in this guide:
• URI structure enables consistent access to collections and resources
• Links in resources, including self links, support discovery
• JSON encoding simplies representation of resources
• HTTP transport provides methods to interact with resources, as well as security, authentication, caching,
and content negotiation
Overview: URI format and structure
A principle of the REST architecture describes the identication of a resource by means of a Uniform
Resource Identier (URI). A URI identies the name of a web resource; in this case, the URI also represents
the tree structure of modules and components in tmsh. You can specify a URI with a web service request
to create, read, update, or delete some component or module of a BIG-IP®system conguration. In the
context of the REST architecture, the system conguration is synonymous with the representation of a
resource, and web service requests read and write that representation using the iControl®REST API.
Tip: Use admin, the default administrative account, for requests to iControl REST. Once you are familiar
with the API, you can create user accounts for iControl REST users with various permissions.
For the URI snippet shown here, the management-ip component of the URI is the fully qualied domain
name (FQDN) or IP address of a BIG-IP device.
https://<management-ip>/mgmt/tm/...
In iControl REST, the URI structure for all requests includes the string /mgmt/tm/ to identify the namespace
for trafc management. Any identiers that you append to that string specify collections.
https://<management-ip>/mgmt/tm/...
The ellipsis in the snippet indicates the location where you specify an organizing collection, which is a
collection of links to other resources in iControl REST. Organizing collections are the functional equivalent
of modules in tmsh. In other words, the organizing collection apm in iControl REST is the apm module. In
iControl REST, you can use the following URI to access all of the resources in the apm collection:
https://192.168.25.42/mgmt/tm/apm
Expanding on that approach, the URI in the following example designates all of the resources in the report
collection. You can think of a collection as the equivalent of a tmsh sub-module. An iControl REST
collection contains collections or resources.
https://192.168.25.42/mgmt/tm/apm/report
The URI in the following example designates a resource, which is a set of entities. In iControl REST, an
entity is a property that you can congure, such as "destAddrMax":2048. A resource may also contain
sub-collections. In the parlance of tmsh, a resource is the equivalent of a component.
https://192.168.25.42/mgmt/tm/apm/report/default-report
Important: iControl REST only supports secure access through HTTPS, so you must include credentials
with each REST call. Use the same credentials you use for the BIG-IP device manager interface.
About resource formats
JavaScript Object Notation (JSON) denes the format for data interchange in iControl®REST. The JSON
standard denes a human-readable format, based in part on the JavaScript programming language. Similar
to the eXtensible Markup Language (XML) common to SOAP web services, JSON describes a structuring
of data for exchange between clients and servers in REST web service requests. iControl REST processes
a request body formatted as JavaScript Object Notation (JSON) format and generates a JSON body in a
response. A response to a DELETE request typically does not include a JSON body.
JSON consists of two structures: name/value pairs (key/value pairs) organized as objects, and ordered lists
of values organized as arrays. An object is contained within curly braces '{}' and an array is contained within
square brackets '[]'. JSON objects can contain objects, strings, numbers, arrays, Boolean values (true or
false), or null. For more information about JSON, see RFC 7159 The JavaScript Object Notation (JSON)
Data Interchange Format.
About creating resources
Create new resources by using the HTTP POST method. iControl®REST supports the POST operation to
create a resource in Access Policy Manager®(APM®). You must include a JSON body with a POST request,
even if the JSON body is empty.
About retrieving resources
Retrieve resources by using the HTTP GET method. iControl®REST supports the GET operation to retrieve
a resource, or a collection of resources, in Access Policy Manager®(APM®). Additionally, iControl REST
supports the Open Data Protocol (OData) $filter query parameter to rene the result set.
About updating resources
Update resources by using either the HTTP PATCH or PUT methods. iControl®REST supports the HTTP
PATCH operation to update a resource in Access Policy Manager®(APM®). Use PATCH to update specic
114
Access Policy Manager
properties and leave other properties unchanged. iControl REST also supports the HTTP PUT operation to
update a resource, with the caveat that all unspecied properties are assigned default values.
About deleting resources
Delete resources by using the HTTP DELETE method. iControl®REST supports the DELETE operation
in Access Policy Manager®(APM®). iControl REST returns an HTTP response code for a delete request
but does not include a JSON body.
HTTP Response Codes
The tables list the common HTTP response codes that iControl®REST generates for every request.
DescriptionReturned forResponse code
Indicates that a request completed successfully.All HTTP methods200 OK
Indicates that a request created a resource, such as when you
create an iControl REST transaction.
POST201 Created
DescriptionReturned forResponse code
Indicates a malformed request, such as an incorrect name for a
resource.
All HTTP methods400 Bad Request
Indicates an omitted HTTP Authorization header, or that
you lack adequate permissions for the request to complete.
All HTTP methods401 Unauthorized
Indicates that the credentials supplied for an administrator lack
adequate permissions for a request, or an attempt to perform an
unsupported action, such as deleting a property.
All HTTP methods403 Forbidden
Indicates an attempt to access a resource that does not exist.All HTTP methods404 Not Found
Indicates an attempt to create a resource that already exists. If
you try to create a resource using the POST method, and the
resource already exists, iControl REST generates this response.
POST, PUT409 Conict
Indicates that the request includes a malformed JSON body in
a request, or possibly that you specied an incorrect
Content-Type header value.
POST, PUT415 Unsupported
Media Type
DescriptionReturned forResponse code
Indicates that the iControl REST process is not available, such
as when the process has not been started.
All HTTP methods500 Internal Server
Error
Indicates that an endpoint does not exist, or the corresponding
tmsh request is unsupported.
POST501 Not
Implemented
Retrieving Access Policy Manager resources
Using iControl®REST, you can query Access Policy Manager®(APM®) resources.
115
iControl®REST API User Guide
1. To discover Access Policy Manager (APM) resources, make a GET request to the endpoint
/mgmt/tm/apm.
GET https://192.168.25.42/mgmt/tm/apm
The response displays the structure of APM collection.
{
"kind":"tm:apm:apmcollectionstate",
"selfLink":"https://localhost/mgmt/tm/apm?ver=12.1.0",
"items":[
{
"reference":{
"link":"https://localhost/mgmt/tm/apm/aaa?ver=12.1.0"
}
},
{
"reference":{
"link":"https://localhost/mgmt/tm/apm/configuration?ver=12.1.0"
}
},
{
"reference":{
"link":"https://localhost/mgmt/tm/apm/epsec?ver=12.1.0"
}
},
{
"reference":{
"link":"https://localhost/mgmt/tm/apm/ntlm?ver=12.1.0"
}
},
{
"reference":{
"link":"https://localhost/mgmt/tm/apm/policy?ver=12.1.0"
}
},
{
"reference":{
"link":"https://localhost/mgmt/tm/apm/profile?ver=12.1.0"
}
},
{
"reference":{
"link":"https://localhost/mgmt/tm/apm/report?ver=12.1.0"
}
},
{
"reference":{
"link":"https://localhost/mgmt/tm/apm/resource?ver=12.1.0"
}
},
{
"reference":{
"link":"https://localhost/mgmt/tm/apm/saml?ver=12.1.0"
}
},
{
"reference":{
"link":"https://localhost/mgmt/tm/apm/sso?ver=12.1.0"
}
},
{
"reference":{
"link":"https://localhost/mgmt/tm/apm/acl?ver=12.1.0"
}
116
Access Policy Manager
},
{
"reference":{
"link":"https://localhost/mgmt/tm/apm/apm-avr-config?ver=12.1.0"
}
},
{
"reference":{
"link":"https://localhost/mgmt/tm/apm/application?ver=12.1.0"
}
},
{
"reference":{
"link":"https://localhost/mgmt/tm/apm/application-family?ver=12.1.0"
}
},
{
"reference":{
"link":"https://localhost/mgmt/tm/apm/application-filter?ver=12.1.0"
}
},
{
"reference":{
"link":"https://localhost/mgmt/tm/apm/log-setting?ver=12.1.0"
}
},
{
"reference":{
"link":"https://localhost/mgmt/tm/apm/risk-class?ver=12.1.0"
}
},
{
"reference":{
"link":"https://localhost/mgmt/tm/apm/session?ver=12.1.0"
}
},
{
"reference":{
"link":"https://localhost/mgmt/tm/apm/swg-scheme?ver=12.1.0"
}
},
{
"reference":{
"link":"https://localhost/mgmt/tm/apm/url-filter?ver=12.1.0"
}
}
]
}
2. To discover one of the resources in APM, such as /ntlm, make a GET request to the endpoint
/mgmt/tm/apm/ntlm.
GET https://192.168.25.42/mgmt/tm/apm/ntlm
The response displays the resources within the /mgmt/tm/apm/ntlm namespace.
{
"kind":"tm:apm:ntlm:ntlmcollectionstate",
"selfLink":"https://localhost/mgmt/tm/apm/ntlm?ver=12.1.0",
"items":[
{
117
iControl®REST API User Guide
"reference":{
"link":"https://localhost/mgmt/tm/apm/ntlm/machine-account?ver=12.1.0"
}
},
{
"reference":{
"link":"https://localhost/mgmt/tm/apm/ntlm/ntlm-auth?ver=12.1.0"
}
}
]
}
Access Policy Manager endpoints
iControl®REST supports the Access Policy Manager®(APM®) endpoints listed here. All endpoints are
relative to the trafc management namespace, /mgmt/tm.
DescriptionEndpoint
Congure authorization, authentication, and accounting (AAA) settings. You
can congure APM to use various servers to provide user authentication,
/apm/aaa
authorization to access resources, and accounting of user activities. APM
supports RADIUS, RSA Native SecurID, and Windows Active Directory, among
others.
Restrict access to host and port combinations with Access Control Lists (ACLs)./apm/acl
Congure settings for Application Visibility and Reporting (AVR)./apm/apm-avr-cong
Specify the web-based applications you can control by modifying the default
allow or block action.
apm/application
Specify categories of applications, such as instant messaging or e-mail./apm/application-family
Specify the application lters you can use to allow or block access to the
applications.
/apm/application-lter
Specify settings for Secure Web Gateway (SWG) initialization./apm/conguration
Congure APM to enable client-side and server-side, endpoint security checks./apm/epsec
Congure APM to log access policy events or audit events./apm/log-setting
Congure APM to use NTLM. You can create a machine account for APM to
join a Windows domain. Authentication requests with a machine account create
a secure channel to communicate with a domain controller.
/apm/ntlm
Congure policy for scheme assignment./apm/policy
Congure prole for trafc handling./apm/prole
Congure settings for reporting./apm/report
Specify network access and web access resource./apm/resource
Specify risk classes./apm/risk-class
Congure APM for Security Assertion Markup Language (SAML) framework
for creating, requesting, and exchanging authentication and authorization data.
/apm/saml
118
Access Policy Manager
DescriptionEndpoint
You can congure APM as a native SAML 2.0 identity provider (IDP), or as
a proxy to another SAML IDP, such as Active Directory Federation Services
(ADFS).
Retrieve and manage user sessions./apm/session
Congure APM to use the Single Sign-On (SSO) feature. You can dene
attributes for user name, password, and authentication methods for SSO, as well
as a number of HTTP form-based SSO object attributes.
/apm/sso
Congure Secure Web Gateway (SWG) schemes to lter and categorize URLs.
A scheme lets you group and schedule URL lters for specic days, or specic
times during a day.
/apm/swg-scheme
Congure APM to use a URL lter to specify one or more URL categories to
allow or block. Using this endpoint, you can create multiple URL lters. With
the exception of default URL lters, you can also delete URL lters.
/apm/url-lter
Configuring LDAP settings in APM
The authentication, authorization, and auditing settings allow you to congure LDAP settings in Access
Policy Manager®(APM®). LDAP is a lightweight implementation of the X.500 Directory Access Protocol
(DAP) supported by a number of vendors. The iControl®REST API allows you to congure the LDAP
server conguration but not the function of an LDAP server.
1. Before you attempt to add an LDAP account and congure it, make a GET request to the
/mgmt/mt/apm/aaa/ldap/example endpoint to get the reference object.
GET https://192.168.25.42/mgmt/tm/apm/aaa/ldap/example
You can use the /example endpoint to get a representation of the APM resource, or any resource in
iControl REST.
{
"kind":"tm:apm:aaa:ldap:ldapcollectionstate",
"selfLink":"https://localhost/mgmt/tm/apm/aaa/ldap/example?ver=12.1.0",
"items":[
{
"propertyDescriptions":{
"address":"",
"adminDn":"",
"adminEncryptedPassword":"",
"appService":"",
"baseDn":"",
"cleanupCache":"",
"description":"",
"groupCacheTtl":"",
"isLdaps":"",
"locationSpecific":"",
"pool":"",
"port":"",
"schemaAttr":{
"groupMember":"",
"groupMemberValue":"",
"groupMemberof":"",
"groupObjectClass":"",
119
iControl®REST API User Guide
"userMemberof":"",
"userObjectClass":""
},
"serversslProfile":"",
"timeout":"",
"usePool":""
},
"address":"any6",
"adminDn":"",
"adminEncryptedPassword":"",
"appService":"",
"baseDn":"",
"cleanupCache":"none",
"description":"",
"groupCacheTtl":30,
"isLdaps":"false",
"locationSpecific":"true",
"pool":"",
"port":389,
"schemaAttr":{
"groupMember":"member",
"groupMemberValue":"dn",
"groupMemberof":"memberOf",
"groupObjectClass":"group",
"userMemberof":"memberOf",
"userObjectClass":"user"
},
"serversslProfile":"",
"timeout":15,
"usePool":"enabled",
"naturalKeyPropertyNames":[
"name",
"partition",
"subPath"
]
}
]
}
2. To congure LDAP server settings to use with APM, make a POST request to the
/mgmt/tm/apm/aaa/ldap endpoint. Make sure that you specify application/json as the content
type.
POST https://192.168.25.42/mgmt/tm/apm/aaa/ldap
{
"name": "test_aaa_ldap",
"address": "10.1.1.1",
"adminDn": "\"CN=administrator, CN=users, DC=mydomain, DC=com\"",
"adminEncryptedPassword": "p4s8w07d",
"usePool": "disabled"
}
This example uses a small subset of properties found in the object. As shown in the JSON, you must
escape the quotes ('\') in the JSON string to preserve the quotes. If you intend to use an LDAP server as
an authentication or query server, you must use the visual policy editor and make the change manually.
The response includes a status code (200 OK) that indicates whether the request succeeded, but iControl
REST also includes the newly created resource in the response.
{
"kind":"tm:apm:aaa:ldap:ldapstate",
"name":"test_aaa_ldap",
"fullPath":"test_aaa_ldap",
120
Access Policy Manager
"generation":30,
"selfLink":"https://localhost/mgmt/tm/apm/aaa/ldap/test_aaa_ldap?ver=12.1.0",
"address":"10.1.1.1",
"adminDn":"CN=Administrator, CN=Users, DC=mydomain, DC=com",
"adminEncryptedPassword":"$M$Uq$lXbiDrLRf0Ogq4zAX0pvYQ==",
"cleanupCache":"none",
"groupCacheTtl":30,
"isLdaps":"false",
"locationSpecific":"true",
"port":389,
"schemaAttr":{
"groupMember":"member",
"groupMemberValue":"dn",
"groupMemberof":"memberOf",
"groupObjectClass":"group",
"userMemberof":"memberOf",
"userObjectClass":"user"
},
"timeout":15,
"usePool":"disabled"
}
3. To delete the LDAP settings, make a DELETE request and specify the LDAP server name
(test_aaa-ldap) from the previous step.
DELETE https://192.168.25.42/mgmt/tm/apm/aaa/ldap/test_aaa_ldap
iControl REST deletes the resource and responds with an HTTP response. The response does not include
a JSON body.
In this example, you congured LDAP server settings. Using the reference object as the starting point, you
create a new LDAP server by specifying a small set of properties. After reviewing the new LDAP server,
you then delete the server by specifying the resource name.
Creating a custom category in APM
On a BIG-IP®system, you have the option to use a default set of categories in a URL database or to dene
URL categories and lters. If you have a Secure Web Gateway (SWG) subscription, you can create custom
URL categories to extend the URL database. If you do not have an SWG subscription, you can still create
custom URL categories. Using the iControl®REST API, you can follow a two-step process to create a
custom URL category and then attach the custom category to a URL lter.
1. To create a custom category, make a GET request to the /sys/url-db/url-category endpoint. Use
the response to determine if a category exists, and if the category is allowed or blocked.
GET https://192.168.25.42/mgmt/tm/sys/url-db/url-category
{
"kind":"tm:sys:url-db:url-category:url-categorycollectionstate",
"selfLink":"https://localhost/mgmt/tm/sys/url-db/url-category?ver=12.1.0",
"items":[
121
iControl®REST API User Guide
{
"kind":"tm:sys:url-db:url-category:url-categorystate",
"name":"Entertainment",
"partition":"Common",
"fullPath":"/Common/Entertainment",
"generation":1,
"selfLink":"https://localhost/mgmt/tm/sys/url-db/url-category/~Common~Entertainment?ver=12.1.0",
"catNumber":10,
"defaultAction":"allow",
"description":"Sites with information about entertainment.",
"displayName":"Entertainment",
"isCustom":"false",
"isRecategory":"false",
"parentCatNumber":0,
"severityLevel":0
},
... (Truncated for readability)
{
"kind":"tm:sys:url-db:url-category:url-categorystate",
"name":"Business",
"partition":"Common",
"fullPath":"/Common/Business",
"generation":1,
"selfLink":"https://localhost/mgmt/tm/sys/url-db/url-category/~Common~Business?ver=12.1.0",
"catNumber":1902,
"defaultAction":"block",
"displayName":"Business",
"isCustom":"true",
"isRecategory":"false",
"parentCatNumber":0,
"severityLevel":0,
"urls":[
{
"name":"http://www.example.com/*",
"type":"glob-match"
},
{
"name":"http://www.example.com/?/",
"type":"exact-match"
}
]
}
]
}
2. After you determine the custom category does not exist, create the custom category. As with other APM
examples, append the /example endpoint to the URL from the previous step if you would like to see
the sample representation of the object.
POST https://192.168.25.42/mgmt/tm/sys/url-db/url-category
{
"displayName": "my-custom-category",
"defaultAction": "block",
"urls": [ ]
}
122
Access Policy Manager
3. To attach the custom category to a URL lter, make a POST request to the /tm/apm/url-filter
endpoint.
POST https://192.168.25.42/mgmt/tm/apm/url-filter
{
"name": "my-url-filter",
"allowedCategories": "my-custom-category"
}
As with any iControl REST request, the response shows the result of the request.
In this example, you created a custom URL category and attached the custom category to a URL lter.
Managing user sessions in APM
Access Policy Manager®(APM®) tracks user sessions with session identiers (session IDs). The
access-info endpoint in APM enables you to make an iControl®REST request for a listing of all user
sessions. The response contains the session ID, user login, and IP address for each session. As part of the
session management process, you can make an iControl REST request to the session endpoint to delete
a specic session.
1. To view the current user sessions in APM, make a GET request to the /mgmt/tm/apm/access-info
endpoint.
GET https://192.168.25.42/mgmt/tm/apm/access-info
The response to this request includes the following data:
{
"apiRawValues": {
"apiAnonymous": {
"apm::access-info" "914c727f (login user=user1) client (IP=10.20.36.2)"
...(Truncated for readability)
"kind": "tm:apm:access-info:access-infostats",
"selfLink": "https://localhost/mgmt/tm/apm/access-info?ver=12.1.0"
}
2. To view the sessions for a specic user name, make a GET request to the mgmt/tm/apm/access-info
endpoint and use the options query parameter to specify the user name.
GET https://192.168.25.42/mgmt/tm/apm/access-info?ver=12.0.0&options=apm-user
In a similar manner, you can also specify an IP address to get a listing of all sessions for a specied IP
address. Use the same query parameter (options) as in the example.
3. To delete a session, make a DELETE request and append the session identier that identies the resource
to the /mgmt/tm/apm/session endpoint.
DELETE https://192.168.25.42/mgmt/tm/apm/session/914c727f
123
iControl®REST API User Guide
The affected user will no longer be able to access resources. The user must log in again.
The response to the request, if successful, is 200 OK.
In this example, you made an iControl REST request to APM to obtain a listing of all user sessions and
made an additional request to delete a specic session.
124
Access Policy Manager
API Life Cycle
REST API life cycle policy
REST API life cycle policy describes an approach to manage the purpose or longevity of REST collections
as well as tmsh resources. Life cycle management presents several use cases that affect resources and
methods, and the REST API life cycle policy is designed to provide useful information about resources and
properties that may be new or experimental, or being phased out. While deprecation of a resource or resource
property represents the most likely use case, other use cases exist for early access features, as well as internal
use or test. You should interpret the deprecation of a resource or property to mean that the use of a resource
or property is discouraged, and not that a resource or resource property will be removed in the near term.
The goal is to make you aware of changes before the changes happen.
The API life cycle policy introduces status values, with NO_STATUS being the default value. The
NO_STATUS value indicates that no determination has been made about a resource or property, and that
REST does not log usage of those resources. REST logs usage of just the resources and properties that
match the status values that you congure. For deprecated and early access resources, a custom REST
header (X-F5-Api-Status) indicates one of the following values:
• DEPRECATED_RESOURCE
• DEPRECATED PROPERTY
• EARLY_ACCESS_RESOURCE
• EARLY_ACCESS_PROPERTY
Using the REST API life cycle changes
The implementation of the REST API Life Cycle Policy provides an API status value and additional
information as log entries for a request. The following examples demonstrate a request with various HTTP
verbs and the corresponding headers (if any), and log entries.
Important: This feature works only with resource collections.
1. To generate the life cycle output for a query of a resource, make a GET request to the
/mgmt/tm/ltm/profile/ocsp-stapling-params endpoint.
GET https://192.168.25.42/mgmt/tm/ltm/profile/ocsp-stapling-params
{
"kind" :
"tm:ltm:profile:ocsp-stapling-params:ocsp-stapling-paramscollectionstate",
"selfLink":
"https://localhost/mgmt/tm/ltm/profile/ocsp-stapling-params?ver=13.0.0"
}
2. To locate the detailed information for the resource, nd the corresponding log entry in the
/var/log/icrd log.
Dec 30 23:59:36 localhost notice icrd_child: 18826,18853,iControl REST Child
Daemon,WARNING,[api-status-warning]: ltm/profile/ocsp-stapling-params:
deprecated
A log message includes an identier, such as [api-status-warning] to indicate log entries for REST
API Life Cycle Management.
3. To generate the output for a query of a resource property, make a GET request to the
/mgmt/tm/ltm/profile/fastl4/fastL4 endpoint.
GET https://192.168.25.42/mgmt/tm/ltm/profile/fastl4/fastL4
{
....
"serverTimestamp": "disabled",
"softwareSynCookie": "disabled",
"synCookieEnable": "enabled",
....
}
4. To locate the detailed information for the resource property, nd the corresponding log entry in the
/var/log/icrd log.
Dec 31 00:05:02 localhost notice icrd_child: 18826,18853, iControl REST
Child
Daemon,WARNING,[api-status-warning]: ltm/profile/fastl4: no status;
properties: deprecated:
ltm/profile/fastl4/hardware-syn-cookie,
ltm/profile/fastl4/software-syn-cookie
5. To generate the life cycle output for the creation of a new resource, make a POST request to the
/mgmt/tm/ltm/profile/ocsp-stapling-params endpoint. Specify the JSON body, as shown.
POST https://192.168.25.42/mgmt/tm/ltm/profile/ocsp-stapling-params
{
"name": "myocsp",
"dnsResolver": "dns-resolver-1"
}
Note: The response includes the header and value X-F5-Api-Status: DEPRECATED_RESOURCE
6. To view the log information for the request, nd the entry in the /var/log/icrd log.
Jan 5 01:14:08 localhost notice icrd_child[2562]: 2562, 2567, iControl
REST Child
Daemon,WARNING,[api-status-warning]: ltm/profile/ocsp-stapling-params:
deprecated
126
API Life Cycle
7. To generate the life cycle output for the creation of a new resource, with the deprecated API allowed
setting set to false, make a POST request to the /mgmt/tm/ltm/profile/ocsp-stapling-params
endpoint. Specify the JSON body, as shown.
POST https://192.168.25.42/mgmt/tm/ltm/profile/ocsp-stapling-params
{
"name": "myocsp",
"dnsResolver": "dns-resolver-1"
}
Note: The response includes the status message HTTP/1.1 404 Not Found.
8. To view the log information for the request, nd the entry in the /var/log/restjavad.0.log log.
Note that the entry appears in a different log le than previous examples.
[WARNING][157][05 Jan 2017 01:23:42 UTC][8100/mgmt/shared/resolver/groups
ForwarderPassThroughWorker] [api-status-warning] The deprecate API
/mgmt/tm/ltm/profile/ocsp-stapling-params/ is not available as per the
/shared/settings/api-status/availability
9. To generate the output for the creation of a resource property, make a POST request to the
/mgmt/tm/ltm/profile/fastl4/fastL4 endpoint. Specify the JSON body, as shown.
POST https://192.168.25.42/mgmt/tm/ltm/profile/fastl4
{
"name": "myfastl4",
"softwareSynCookie": "enabled"
}
Note: The response includes the header and value X-F5-Api-Status: DEPRECATED_PROPERTY.
10. To view the log information for the request, nd the entry in the /var/log/icrd log.
Jan 5 17:26:53 localhost notice icrd_child[2562]: 2562, 2568, iControl
REST Child
Daemon,WARNING,[api-status-warning]: ltm/profile/fastl4: no status;
properties: deprecated:
ltm/profile/fastl4/hardware-syn-cookie,
ltm/profile/fastl4/software-syn-cookie
127
iControl®REST API User Guide
11. To generate the life cycle output for the creation of a new resource property, with the deprecated API
allowed setting set to false, make a POST request to the /mgmt/tm/ltm/profile/fastl4 endpoint.
Specify the JSON body, as shown.
POST https://192.168.25.42/mgmt/tm/ltm/profile/fastl4
{
"name": "myfastl4",
"softwareSynCookie": "enabled"
}
Note: The response includes the status message HTTP/1.1 404 Not Found, as well as the header
and value X-F5-Api-Status: DEPRECATED_PROPERTY.
12. To view the log information for the request, nd the entry in the /var/log/icrd log.
Jan 5 17:36:45 localhost notice icrd_child[2562]: 2562, 2567, iControl
REST Child
Daemon,WARNING,[api-status-warning]: ltm/profile/fastl4: no status;
properties: deprecated:
ltm/profile/fastl4/software-syn-cookie
Using the REST API life cycle changes with tmsh
The following examples show the tmsh equivalent of the previous REST examples.
1. To generate the API life cycle output for a resource, run a tmsh command to list the resource.
(tmos)# list ltm profile ocsp-stapling-params
api-status-warning] ltm/profile/ocsp-stapling-params is deprecated
ltm profile ocsp-stapling-params ocsp-cur {
dns-resolver dns-resolver-cur
}
2. To locate the detailed information for the resource, nd the corresponding log entry in the
/var/log/ltm log.
Dec 30 16:00:43 localhost warning tmsh[1409]: 01420013:4: [api-status-warning]
ltm/profile/ocsp-stapling-params is deprecated
3. To generate the API life cycle output for a resource property, run a tmsh command as shown.
(tmos)# list ltm profile fastl4 fastL4 software-syn-cookie
[api-status-warning] ltm/profile/fastl4, properties : deprecated :
software-syn-cookieltm profile fastl4 fastL4 {
...
reassemble-fragments disabled
128
API Life Cycle
reset-on-timeout enabled
software-syn-cookie enabled
}
4. To locate the detailed information for the resource property, nd the corresponding log entry in the
/var/log/ltm log.
Dec 30 16:02:49 localhost warning tmsh[1731]: 01420013:4: [api-status-warning]
ltm/profile/fastl4, properties : deprecated : software-syn-cookie
5. To generate the life cycle output for the creation of a new resource, run a tmsh command as shown.
The output appears after the command.
(tmos)# create ltm profile ocsp-stapling-params myocsp dns-resolver
dns-resolver-1
[api-status-warning] ltm/profile/ocsp-stapling-params is deprecated
6. To locate the detailed information for the resource, nd the corresponding log entry in the
/var/log/ltm log
Jan 5 09:49:54 localhost warning tmsh[4542]: 01420013:4: [api-status-warning]
ltm/profile/ocsp-stapling-params is deprecated
7. To generate the life cycle output for the creation of a new resource, with the deprecated API allowed
setting set to false, run a tmsh command as shown. The output appears after the command.
(tmos)# create ltm profile ocsp-stapling-params myocsp dns-resolver
dns-resolver-1
[api-status-warning] ltm/profile/ocsp-stapling-params is deprecated. This
command is not
available or has properties which are not available.
8. To locate the detailed information for the resource, nd the corresponding log entry in the
/var/log/ltm log.
Jan 5 09:49:01 localhost warning tmsh[4493]: 01420013:4: [api-status-warning]
ltm/profile/ocsp-stapling-params is deprecated
9. To generate the output for the creation of a resource property, run a tmsh command as shown. The output
appears after the command.
(tmos)# create ltm profile fastl4 myfastl4 software-syn-cookie enabled
[api-status-warning] ltm/profile/fastl4, properties : deprecated :
software-syn-cookie
129
iControl®REST API User Guide
10. To locate the detailed information for the resource property, nd the corresponding log entry in the
/var/log/ltm log.
Jan 5 09:44:28 localhost warning tmsh[4426]: 01420013:4: [api-status-warning]
ltm/profile/fastl4, properties : deprecated : software-syn-cookie
11. To generate the life cycle output for the creation of a new resource, with the deprecated API allowed
setting set to false, run a tmsh command as shown. The output appears after the command.
(tmos)# create ltm profile fastl4 myfastl4 software-syn-cookie enabled
[api-status-warning] ltm/profile/fastl4, properties : deprecated :
software-syn-cookie
12. To locate the detailed information for the resource property, nd the corresponding log entry in the
/var/log/ltm log.
Jan 5 09:44:28 localhost warning tmsh[4426]: 01420013:4: [api-status-warning]
ltm/profile/fastl4, properties : deprecated : software-syn-cookie
Configuring the REST API life cycle settings
The REST API Life Cycle Policy supports congurable API states and log settings. By enabling specic
settings, you enable the logging of information by REST and tmsh.
1. To view the settings for REST, make a GET request.
GET https://192.168.25.42/mgmt/shared/settings/api-status/availability/
The query results will be similar to the following snippet:
{
"deprecatedApiAllowed": "true",
"earlyAccessApiAllowed": "true",
"testOnlyApiAllowed": "false"
}
Important: These settings affect the visibility of a resource. If you specify any of the states as disabled,
you will not be able to view that resource in REST requests or in tmsh. A REST request will generate
a 404 (Not Found) response code. In tmsh, tab completion will not expose these resources.
130
API Life Cycle
2. To change an api-status setting, make a PATCH or POST request. In the JSON body, specify the
visibility settings to change. For example,
PATCH https://192.168.25.42/mgmt/shared/settings/api-status/availability/
{
"earlyAccessApiAllowed": "false"
}
Conrm that the change was successful by making a query request.
3. To specify the resource settings that generate log entries, make a GET request.
GET https://192.168.25.42/mgmt/shared/settings/api-status/log/resource
The query results will again be similar to the following:
{
"deprecatedApiAllowed": "true",
"earlyAccessApiAllowed": "true",
"testOnlyApiAllowed": "false"
}
4. To specify the property resource settings that generate log entries, make a GET request (results are
omitted).
GET
https://192.168.25.42/mgmt/shared/settings/api-status/log/resource-property
For either endpoint, make a PATCH or POST request as shown to modify any of the settings.
In this topic, you queried and congured the visibility and logging settings for the API life cycle.
Configuring the REST API life cycle settings with tmsh
The REST API life cycle policy supports congurable API states and log settings. You can congure API
states and log settings with tmsh commands.
1. To view the settings, type the following tmsh command.
(tmos)# list mgmt shared settings api-status availability
2. To modify the deprecated setting, type the following tmsh command.
(tmos)# modify mgmt shared settings api-status availability {
deprecatedApiAllowed value false }
The command changes the state to disabled.
3. To view the settings for log resources, type the following tmsh command
(tmos)# list mgmt shared settings api-status log resource
131
iControl®REST API User Guide
You can view the log setting for resource properties by specifying resource-property instead of
resource in the command.
mgmt shared settings api-status log resource
{
deprecatedApiAllowed true
testOnlyApiAllowed true
earlyAccessApiAllowed true
}
In this topic, you used tmsh commands to view and modify API status and log settings.
132
API Life Cycle
Additional Features
About the example suffix
The inclusion of the /example sufx at the end of a URI prompts iControl®REST to generate a sample
representation of a resource. The /example sufx may be used in a GET request to produce a representation
that includes all properties, including null properties. The sample representation also includes the help text
strings that describe each property and a list of natural keys for a resource. A natural key consists of one or
more user-friendly properties that uniquely identify a resource, such as area code/phone number.
In iControl REST, a natural key is represented in JSON as a naturalKeyPropertyNames property, which
is an array of name,partition, and subPath. The name,partition, and subPath form a full path to
an object. For resources in the Common partition, iControl REST omits the partition name as a natural key.
If an object is a singleton object, the naturalKeysPropertyNames array is empty.
BIG-IP®system components that support only the TMSH commands SHOW,LIST,DELETE,LOAD,SAVE,
INSTALL, or RUN do not have default eld values. For those components, an iControl REST request to the
/example endpoint does not generate a response with default values.
The sample representation of Application Security Manager™(ASM™) resources includes only default
values and possible enumeration values. The sample representation of ASM resources does not include
descriptions of the properties as help text.
The sample representation species a default value for a property, if a default value exists. If a property has
no default value, the representation includes:
• An empty string ("") for a string property
• Zero (0) for a numerical property
• False for a Boolean property
• An empty JSON array or object
If a property takes a value from an enumeration, the representation displays the acceptable values as an
array. iControl REST also appends the sufx Enums to the name of this array to identify the enumeration.
Tip: Copy the sample representation, make changes to the copy, and then paste the changes into the JSON
body of a POST request.
About Access Policy Manager
Access Policy Manager®(APM®) provides secure identity and access management for a BIG-IP®system.
iControl®REST exposes the APM endpoints to enable programmatic access to APM resources and the
benets of automation.
APM adheres to the REST principles described previously in this guide:
• URI structure enables consistent access to collections and resources
• Links in resources, including self links, support discovery
• JSON encoding simplies representation of resources
• HTTP transport provides methods to interact with resources, as well as security, authentication, caching,
and content negotiation
About HTTP response codes
Responses to all iControl®REST requests contain a response code, as listed here.
Success responses
DescriptionResponse code
Indicates success for all methods.200 OK
Error responses
DescriptionHTTP
methods
Response code
Possible causes include:all400 Bad Request
• malformed HTTP request
• incorrect name for a resource in a request
Possible causes include:all401 Unauthorized
• missing HTTP authorization header
• insufcient permissions for the credentials supplied for an
administrator
Possible causes include:all403 Forbidden
• insufcient permissions for the credentials supplied for an
administrator
• attempt to perform an unsupported action, such as deleting a
property
Possible causes include:all404 Not Found
• attempting to access a resource that no longer exists in the
database
Possible causes include:POST, PUT409 Conict
• attempting to create a resource that already exists
Indicates a conict between the requested state change and the
current state of the resource. For example, this is the error response
if you POST a resource that already exists.
Possible causes include:POST, PUT415 Unsupported Media
Type • specifying an incorrect Content-Type header value
• specifying a malformed JSON body with a POST or PUT
request
134
Additional Features
DescriptionHTTP
methods
Response code
Possible causes include:all500 Internal Server
Error • attempting to access iControl REST when the process is not
running
Possible causes include:POST501 Not Implemented
• attempting to access a endpoint that does not exist
• attempting to invoke an unsupported tmsh command through
iControl REST
About log files
From the console or an SSH connection to your BIG-IP®device, you can nd the following log les for
iControl®REST:
•/var/log/restjavad-audit.0.log shows all authentications to the iControl REST service. This
is an ordered list of every REST call.
•/var/log/restjavad.0.log contains information about connections to the iControl REST service,
such as errors returned.
•/var/log/icrd shows the actions of the icrd process, which manages the threads for processing the
REST calls.
•/var/log/ltm contains messages from mcpd, a process called by icrd that manages the system
conguration.
Use standard Unix commands to work with these les, such as tail,grep, and less. In this example,
the session logs in to a BIG-IP system through ssh and uses tail -f to monitor the
/var/log/restjavad-audit.0.log log le:
juser@bench2:~/$ ssh root@192.168.25.42
Password: default
Last login: Fri Mar 29 09:03:25 2013 from 192.168.98.174
[root@localhost:Active:Standalone] config # tail -f
/var/log/restjavad-audit.0.log
[I][339][29 Mar 2013 16:04:06 UTC][ForwarderPassThroughWorker] \
[run]{"user":"admin","method":"PUT",\
"uri":"http://localhost:8100/mgmt/tm/ltm/pool/dns-pool2",\
"status":"succeeded","from":"192.168.96.37"}
[I][340][29 Mar 2013 16:04:06 UTC][ForwarderPassThroughWorker] \
[run]{"user":"admin","method":"GET",\
"uri":"http://localhost:8100/mgmt/tm/ltm/pool","\
status":"succeeded","from":"192.168.96.37"}
[I][341][29 Mar 2013 16:04:06 UTC][ForwarderPassThroughWorker] \
[run]{"user":"admin","method":"DELETE",\
"uri":"http://localhost:8100/mgmt/tm/ltm/pool/test-pool2",\
"status":"succeeded","from":"192.168.96.37"}
[I][342][29 Mar 2013 16:04:07 UTC][ForwarderPassThroughWorker] \
[run]{"user":"admin","method":"POST",\
"uri":"http://localhost:8100/mgmt/tm/sys/folder",\
"status":"succeeded","from":"192.168.96.37"}
[I][343][29 Mar 2013 16:04:07 UTC][ForwarderPassThroughWorker]\
[run] {"user":"admin","method":"DELETE",\
"uri":"http://localhost:8100/mgmt/tm/sys/folder/~fw_objs",\
"status":"succeeded","from":"192.168.96.37"}
135
iControl®REST API User Guide
[I][344][29 Mar 2013 16:04:07 UTC][ForwarderPassThroughWorker]\
[run] {"user":"admin","method":"DELETE",\
"uri":"http://localhost:8100/mgmt/tm/sys/folder/~eu~east~romania",\
"status":"succeeded","from":"192.168.96.37"}
[I][345][29 Mar 2013 16:04:07 UTC][ForwarderPassThroughWorker]\
[run] {"user":"admin","method":"POST",\
"uri":"http://localhost:8100/mgmt/shared/authz",\
"status":"succeeded","from":"192.168.96.37"}
[I][346][29 Mar 2013 16:04:07 UTC][ForwarderPassThroughWorker]\
[run] {"user":"admin","method":"GET",\
"uri":"http://localhost:8100/mgmt/shared/authz",\
"status":"succeeded","from":"192.168.96.37"}
[I][347][29 Mar 2013 16:04:10 UTC][ForwarderPassThroughWorker]\
[run] {"user":"dns_admin","method":"GET",\
"uri":"http://localhost:8100/mgmt/tm/sys",\
"status":"succeeded","from":"192.168.96.37"}
[I][350][29 Mar 2013 16:04:10 UTC][ForwarderPassThroughWorker]\
[run] {"user":"admin","method":"GET",\
"uri":"http://localhost:8100/mgmt/tm/ltm/pool/http-pool?$stats=true",\
"status":"succeeded","from":"192.168.96.37"}
...
If you need to adjust the logging levels for icrd, contact F5®Networks Technical Support
(http://www.f5.com/support/).
About public URIs
A URI is considered to be public if you can access it through an iControl®REST request. In general, all of
the following are public:
• Trafc Management Shell (tmsh) modules
• Trafc Management Shell (tmsh) components
• Any component properties that are accessible through the tmsh show command.
To view the component properties, make a GET request of a parent component. By default, you cannot use
a GET request to obtain them directly through a public URI.
The public URIs exist to provide direct access to some of those component properties. The iControl REST
process allows these for convenience, for situations where a PUT request of the entire containing object (a
component or collection) would be unwieldy.
In many cases, the second-to-last part of the path is the name of a component, and you need to provide a
specic object name for that component before the nal part of the path. For example, to access the public
URI /mgmt/tm/gtm/pool/members, you must specify the DNS pool for which you want members, such
as /mgmt/tm/gtm/pool/pool5/members for the members of pool5.
136
Additional Features
Legal Notices
Legal notices
Publication Date
This document was published on August 11, 2017.
Publication Number
MAN-0526-03
Copyright
Copyright ©2017, F5 Networks, Inc. All rights reserved.
F5 Networks, Inc. (F5) believes the information it furnishes to be accurate and reliable. However, F5 assumes
no responsibility for the use of this information, nor any infringement of patents or other rights of third
parties which may result from its use. No license is granted by implication or otherwise under any patent,
copyright, or other intellectual property right of F5 except as specically described by applicable user
licenses. F5 reserves the right to change specications at any time without notice.
Trademarks
For a current list of F5 trademarks and service marks, see
http://www.f5.com/about/guidelines-policies/trademarks/.
All other product and company names herein may be trademarks of their respective owners.
Patents
This product may be protected by one or more patents indicated at: https://f5.com/about-us/policies/patents
Link Controller Availability
This product is not currently available in the U.S.
Export Regulation Notice
This product may include cryptographic software. Under the Export Administration Act, the United States
government may consider it a criminal offense to export this product from the United States.
RF Interference Warning
This is a Class A product. In a domestic environment this product may cause radio interference, in which
case the user may be required to take adequate measures.
FCC Compliance
This equipment has been tested and found to comply with the limits for a Class A digital device pursuant
to Part 15 of FCC rules. These limits are designed to provide reasonable protection against harmful
interference when the equipment is operated in a commercial environment. This unit generates, uses, and
can radiate radio frequency energy and, if not installed and used in accordance with the instruction manual,
may cause harmful interference to radio communications. Operation of this equipment in a residential area
is likely to cause harmful interference, in which case the user, at his own expense, will be required to take
whatever measures may be required to correct the interference.
Any modications to this device, unless expressly approved by the manufacturer, can void the user's authority
to operate this equipment under part 15 of the FCC rules.
Canadian Regulatory Compliance
This Class A digital apparatus complies with Canadian ICES-003.
Standards Compliance
This product conforms to the IEC, European Union, ANSI/UL and Canadian CSA standards applicable to
Information Technology products at the time of manufacture.
138
Legal Notices
Index
A
administrative partition
about 45
AJAX JSON
configuring 111
AJAX JSON login 110
anomaly session opening ASM
settings 96
anomaly session transactions ASMsettings 95
API life cycle
understanding changes 125
using tmsh 128
API life cycle changes 125
API Life Cycle Policy 125
API life cycle settings
configuring 130
configuring with tmsh 131
API versions URI
about 19
APM
about Access Policy Manager 113, 133
APM endpoint 118
Application Security Manager
differences 67
policy 74, 83
schema 83
signatures 78
vulnerability 85
vulnerability resolution 91
ASM Application Security Manager
deleting 74
POST 72
retrieving with GET 69
updating with PATCH 73
ASM policies
exporting 76
ASM policy
applying 77
importing 75
ASM policy builder settings
retrieving 103
ASM policy builder suggestions
about using 102
modifying 104
ASM policy revisions
restoring 84
ASM schema
uploading 83
ASM signatures
exporting 80
updating 79
ASM vulnerabilities
importing 86
resolving 91
ASM vulnerability
initiating 88
terminating 90
ASM web scraping settings
about 99
modifying 100
retrieving 99
asynchronous task iControl REST
using 54
asynchronous tasks, iControl REST
about creating 53
asynchronous tasks endpoints 53
authentication iControl REST 20
B
Bot detection settings ASM 95
C
camel case
for JSON properties in iControl REST 19
check
ASM signatures 79
configuration settings
ASM web scraping 94
CORS
client request headers 21
overview of cross-origin resource sharing 20
response headers 21
cp command
using 57
custom URL category
configuring 121
D
deleting
Access Policy Manager APM 44
Device ID
about ASM features 105
device identification fingerprinting 105
E
enforce method URL 106
Error codes
in iControl REST responses 134
Expanding an iControl REST component
limits 31
Expanding an iControl-REST component 32
external authentication iControl REST
using 22
F
format
for JSON properties in iControl REST 19
139
Index
G
generate POST commands 58
H
HTTP
semantics 13
HTTP response codes 115
I
iControl
about user account 20
iControl null values and REST flags
about 17
iControl REST
discovering modules and components 25
log files 135
iControl REST properties
about 16
iControl REST transactions
validating 50
icrd log files 135
important changes API 7
install POST command
updating components 58
J
JSON
getting show content instead of list content 35
JSON format
about 14
JSON format POST and PUT
about 39
JSON resource format
about 114
L
LDAP APM
configuring 119
learning suggestion object 101
life cycle policy
for REST API 125
load POST commands 59
Logging levels
contact Support to change 135
Logs
for iControl REST 135
M
mv command
using 60
O
OData
pagination 27
P
Paging 29
Partition
accessing 34
adding or modifying in 42
deleting 47
partitions
creating folders 45
policy
for REST API life cycle 125
public URIs 136
publish POST commands
using 60
Q
query parameters
about 28
R
Read-only properties
silently ignored in PUT and POST operations 41
reboot POST commands 60
relative partitions
filtering 43
Representational State Transfer
about 7
reserved ASCII characters
about 12
reset-stats POST commands 61
resource
creating with iControl 39
resource PATCH
modifying 40
resources, collections
about creating 114
about deleting 115
about retrieving 114
about updating 114
Response codes
in iControl REST responses 134
REST API life cycle changes
understanding 125
REST API life cycle policy 125
restart POST commands 61
REST resource identifiers
about 13
retrieving
/example endpoint 133
Access Policy Manager APM 115
run POST command
and config sync HA pair 62
140
Index
S
session awareness 106
session hijack
preventing 107
settings suspicious client ASM
settings 98
signatures
retrieving 81
signature systems
retrieving 82
start POST commands 64
string encoding standards
about 19
T
threshold session opening ASM
settings 97
tmsh global commands, GET
about 57
tmsh property names
about 18
transaction
committing 52
creating 50
modifying 51
transaction atomic requests
about 49
transaction phases
about 49
U
URI about 13
URI format and structure
overview 11, 113
user sessions APM
managing 123
V
vulnerabilities
resolving 92
vulnerability assessment subscriptions
querying 87
W
WebSockets
107
managing 107
141
Index
142
Index

Navigation menu