iControl® REST User Guide - F5 Networks · iControl® REST User Guide Version 11.4. Table of Contents Legal Notices ... ARX,AskF5,ASM,BIG-IP,BIG-IQ,CloudExtender,CloudFucious,CloudManager,Clustered

iControl® REST User Guide

Version 11.4

Table of Contents

Legal Notices..............................................................................................................................5

Adding iControl REST service...................................................................................................7

Showing iControl REST status...........................................................................................7

Stopping iControl REST.....................................................................................................8

Restarting iControl REST........................................................................................8

About URI format........................................................................................................................9

About public URIs............................................................................................................10

About JSON format for GET returns.......................................................................................11

About JSON format for components................................................................................13

About name formatting in iControl REST JSON and tmsh....................................15

About null values for flags.....................................................................................15

About names that differ from their tmsh counterparts...........................................17

About JSON format for POST and PUT...........................................................................17

Discovering all modules and components in iControl REST...............................................19

Paging through large collections......................................................................................22

Expanding iControl-REST component links.....................................................................24

Understanding iControl REST expansion..............................................................27

Accessing an administrative partition or folder.................................................................28

Getting Show content instead of List content...................................................................29

Adding new configurations......................................................................................................33

Modifying a configuration object.......................................................................................34

Modifying a collection............................................................................................34

Modifying a single object in a collection................................................................37

Understanding how iControl REST manages read-only properties ................................37

Adding or modifying in a partition.....................................................................................38

About relative partitions and folders......................................................................39

Adding an object with a forward slash character in its name...........................................39

Deleting a configuration object.........................................................................................40

Adding a partition.....................................................................................................................43

Deleting a partition...........................................................................................................43

3

Table of Contents

Saving configuration files........................................................................................................45

About HTTP response codes...................................................................................................47

About log files...........................................................................................................................49

4

Table of Contents

Legal Notices

Publication Date

This document was published on June 10, 2013.

Publication Number

MAN-0284-00

Copyright

Copyright © 2012-2013, F5 Networks, Inc. All rights reserved.

F5 Networks, Inc. (F5) believes the information it furnishes to be accurate and reliable. However, F5 assumesno responsibility for the use of this information, nor any infringement of patents or other rights of thirdparties 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 specifically described by applicable userlicenses. F5 reserves the right to change specifications at any time without notice.

Trademarks

AAM, Access Policy Manager, Advanced Client Authentication, Advanced Firewall Manager, AdvancedRouting, AFM, Alive With F5, APM, Application Acceleration Manager, Application Security Manager,ARX, AskF5, ASM, BIG-IP, BIG-IQ, Cloud Extender, CloudFucious, Cloud Manager, ClusteredMultiprocessing, CMP, COHESION, Data Manager, DevCentral, DevCentral [DESIGN], DNS Express,DSC, DSI, Edge Client, Edge Gateway, Edge Portal, ELEVATE, EM, Enterprise Manager, ENGAGE, F5,F5 [DESIGN], F5 Certified [DESIGN], F5 Networks, Fast Application Proxy, Fast Cache, FirePass, GlobalTrafficManager, GTM,GUARDIAN, iApps, IBR, Intelligent Browser Referencing, Intelligent Compression,IPv6 Gateway, iControl, iHealth, iQuery, iRules, iRules OnDemand, iSession, L7 Rate Shaping, LC, LinkController, Local TrafficManager, LTM, LineRate, LineRate Systems [DESIGN], LROS,Message SecurityManager, MSM, OneConnect, Packet Velocity, PEM, Policy Enforcement Manager, Protocol SecurityManager, PSM, Real Traffic Policy Builder, ScaleN, Signalling Delivery Controller, SDC, SSLAcceleration,StrongBox, SuperVIP, SYN Check, TCP Express, TDR, TMOS, Traffic Management Operating System,Traffix Systems, Traffix Systems (DESIGN), Transparent Data Reduction, UNITY, VAULT, VIPRION,vCMP, VE F5 [DESIGN], Virtual Clustered Multiprocessing, WA, WAN Optimization Manager,WebAccelerator, WOM, and ZoneRunner, are trademarks or service marks of F5 Networks, Inc., in theU.S. and other countries, and may not be used without F5's express written consent.

All other product and company names herein may be trademarks of their respective owners.

Export Regulation Notice

This product may include cryptographic software. Under the Export Administration Act, the United Statesgovernment 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 whichcase 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 pursuantto 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, andcan 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 areais likely to cause harmful interference, in which case the user, at his own expense, will be required to takewhatever measures may be required to correct the interference.

Anymodifications to this device, unless expressly approved by themanufacturer, can void the user's authorityto 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 toInformation Technology products at the time of manufacture.

6

Legal Notices

Adding iControl REST service

The iControl®REST service is a public API based on the Representational State Transfer (REST) architecture.This is an interface used for managing a BIG-IP® device. You can access a RESTURI on the BIG-IP systemto GET, POST, PUT (edit), or DELETE any part of the system configuration.

Log in to tmsh on your BIG-IP device before you begin adding the iControl REST service to it.

Run the modify sys service icrd add command to add and start iControl REST. To do so, youneed to type icrd in its entirety; command completion (with the Tab key) cannot function for icrduntil it is added. For example:

root@(BIG-IP1)(...)(tmos)# modify sys service icrd addWARNING: This early-access feature comes with minimaldocumentation and testing. Version control is not implemented;therefore any scripts that you write using this API versionmay not work with subsequent releases.root@(BIG-IP1)(...)(tmos)#

You can now make REST calls to this BIG-IP device, at https://management-ip/mgmt/tm, wheremanagement-ip is the same IP address you used to connect to tmsh.

You need to add iControl REST again after each time you install a new image or hotfix.

Showing iControl REST status

You can use this command to show whether or not iControl® REST is running. The output shows the Unixprocess ID (PID) of the iControl REST daemon, the amount of time since it last started, and the number oftimes it started since the last time iControl REST was enabled.

Run the show sys service icrd command to see the current status of the iControl REST daemon.For example:

root@(BIG-IP1)(...)(tmos)# show sys service icrdicrd run (pid 17316) 16 minutes, 2 startsroot@(BIG-IP1)(...)(tmos)#

This shows that someone has started the iControl REST daemon twice, and the daemon has been activefor a short time.

Stopping iControl REST

You can stop iControl® REST to prevent REST access to the BIG-IP® device. This prevents REST clientsfrom monitoring or managing the system.

Run the stop sys service icrd command to stop iControl-REST processing. For example:

root@(BIG-IP1)(...)(tmos)# stop sys service icrdroot@(BIG-IP1)(...)(tmos)#

After you stop icrd, you can no longer make REST calls to this BIG-IP device.

Restarting iControl REST

You can start iControl® REST with this command if the service is stopped.

Run the start sys service icrd command to restart the iControl REST service. For example:

root@(BIG-IP1)(...)(tmos)# start sys service icrdroot@(BIG-IP1)(...)(tmos)#

You can now make REST calls to this BIG-IP® device, at https://management-ip/mgmt/tm, wheremanagement-ip is the same IP address you used to connect to tmsh.

8

Adding iControl REST service

About URI format

The iControl® REST service is used for managing a BIG-IP® device through HTTP calls. You can accessa REST URI on the BIG-IP system to GET, POST, PUT (edit), or DELETE any part of the systemconfiguration. The URI is based on the tree of modules and components in tmsh; it contains a base URIfollowed by a path through one or more tmsh modules to a component.

The iControl REST service only supports secure access through HTTPS, so you must include administrationcredentials with each REST call. You can use the same credentials as when logging into the BIG-IP devicemanager interface.

The default administrative account, admin, is the only account that is guaranteed to have access to the entireiControl-REST interface. Use this account for your initial access to iControl REST.

Module URI

https://management-ip/mgmt/tm/module

This URI accesses all of the sub-modules and/or components under the given module. The management-ipis the BIG-IP device that answers this REST query.

For example, you could use the following URI (on a particular BIG-IP server) to access all of the componentsand sub-modules under the ltm module:

https://192.168.25.42/mgmt/tm/ltm

Sub-module URI

https://management-ip/mgmt/tm/module/sub-module

This accesses all of the sub-modules and/or components under the given sub-module.

Component URI

https://management-ip/mgmt/tm/module[/sub-module]/component

This accesses details about the given component. The TrafficManagement Shell (tmsh) Reference documentsthe hierarchy of modules and components, and identifies details of each component.

Use standard URL encoding for non-ASCII characters

Some BIG-IP configuration objects require non-ASCII characters or a percent sign (%) to specify them.For example, an IP address in a non-default route domain is expressed with a percent sign (such as192.168.25.90%3 for an address in route domain 3). For iControl REST, use the standard URL encodingfor these characters, such as %25 in place of %, (192.168.25.90%253).

If you use the forward slash (/) character in a query option, you substitute a tilde (~) for the forward slash(/) instead of the standard URL encoding.

http://www.w3schools.com/tags/ref_urlencode.asp

About public URIs

A public URI is one that you can access through iControl® REST. All of the following URIs are public:

• tmsh modules,• tmsh components, and• component properties that are accessible through the tmsh show command.

The remaining component properties are visible in a GET return of their parent component. By default, youcan not GET them directly through a public URI.

The following public URIs exist to provide direct access to some of those component properties. The iControlREST process allows these for convenience, for situations where a PUT of the entire containing object (acomponent or collection) would be unwieldy:

/mgmt/tm/apm/aaa/oam/accessgates /mgmt/tm/apm/aaa/securid/config-files/mgmt/tm/apm/policy/agent/endpoint-check-software/items/mgmt/tm/apm/policy/customization-group/templates /mgmt/tm/apm/profile/access/domain-groups/mgmt/tm/apm/profile/connectivity/client-policy /mgmt/tm/apm/resource/app-tunnel/apps/mgmt/tm/apm/resource/client-traffic-classifier/entries /mgmt/tm/apm/resource/network-access/optimized-app/mgmt/tm/apm/resource/portal-access/items /mgmt/tm/apm/resource/sandbox/files/mgmt/tm/apm/sso/form-basedv2/forms /mgmt/tm/auth/remote-role/role-info /mgmt/tm/gtm/pool/members/mgmt/tm/gtm/server/virtual-servers /mgmt/tm/ltm/dns/dnssec/key/generation/mgmt/tm/ltm/policy-strategy/operands /mgmt/tm/ltm/policy/rules /mgmt/tm/ltm/policy/rules/actions/mgmt/tm/ltm/policy/rules/conditions /mgmt/tm/ltm/pool/members /mgmt/tm/ltm/profile/analytics/alerts/mgmt/tm/ltm/profile/analytics/traffic-capture /mgmt/tm/ltm/profile/rewrite/uri-rules/mgmt/tm/ltm/virtual/fw-rules /mgmt/tm/net/route-domain/fw-rules/mgmt/tm/net/router-advertisement/prefixes /mgmt/tm/net/self/fw-rules /mgmt/tm/net/wccp/services/mgmt/tm/pem/policy/rules /mgmt/tm/pem/policy/rules/flow-info-filters/mgmt/tm/security/dos/profile/application /mgmt/tm/security/dos/profile/protocol-dns/mgmt/tm/security/dos/profile/protocol-sip /mgmt/tm/security/firewall/global-rules/rules/mgmt/tm/security/firewall/management-ip-rules/rules /mgmt/tm/security/firewall/policy/rules/mgmt/tm/security/firewall/rule-list/rules /mgmt/tm/security/log/profile/application/mgmt/tm/security/log/profile/network /mgmt/tm/security/log/profile/protocol-dns/mgmt/tm/security/log/profile/protocol-sip /mgmt/tm/sys/application/template/actions/mgmt/tm/sys/file/apache-ssl-cert/bundle-certificates /mgmt/tm/sys/file/ssl-cert/bundle-certificates/mgmt/tm/sys/file/system-ssl-cert/bundle-certificates /mgmt/tm/sys/icall/handler/perpetual/subscriptions/mgmt/tm/sys/icall/handler/triggered/subscriptions /mgmt/tm/sys/ltcfg-class/fields/mgmt/tm/sys/ltcfg-instance/fields /mgmt/tm/sys/ntp/restrict /mgmt/tm/sys/snmp/communities/mgmt/tm/sys/snmp/traps /mgmt/tm/sys/snmp/users /mgmt/tm/wam/policy/nodes/mgmt/tm/wam/policy/nodes/invalidations /mgmt/tm/wam/policy/nodes/invalidations/cache-content/mgmt/tm/wam/policy/nodes/invalidations/request /mgmt/tm/wam/policy/nodes/matching/mgmt/tm/wam/policy/nodes/proxy /mgmt/tm/wam/policy/nodes/proxy-override/mgmt/tm/wam/policy/nodes/substitutions /mgmt/tm/wam/policy/nodes/variation

In many cases, the second-to-last part of the path is the name of a component, and you need to provide aspecific object name for that component before the final part of the path. For example, to access the publicURI /mgmt/tm/gtm/pool/members, you must specify the GTM™ pool for which you want members,such as /mgmt/tm/gtm/pool/poo5/members for the members of pool5.

10

About URI format

About JSON format for GET returns

iControl® REST returns its answers in JavaScript Object Notation (JSON, specified in RFC 4627) format.

Curl, a common Unix utility for accessing URIs, is used in the example below to make an iControl RESTcall on a particular BIG-IP® device. The curl utility uses the following general syntax:

curl -k -u username:password -X http-method uri

Where:

• username and password are the credentials for a BIG-IP administrator, such as admin:admin;• http-method is GET, POST, PUT, or DELETE (GET is the default); and• uri identifies the BIG-IP resource (for example, 192.168.25.42/mgmt/tm/ltm).

This example uses curl to retrieve all information about the ltmmodule at 192.168.25.42. The responseis a JSON-formatted collection of items in LTM®:

juser@bench2:~/$ curl -k -u admin:admin -H "Content-Type: \application/json" -X GET \https://192.168.25.42/mgmt/tm/ltm \|python -m json.tool

{"currentItemCount": 22,"items": [

{"reference": {

"link": "https://localhost/mgmt/tm/ltm/auth"}

},{

"reference": {"link": "https://localhost/mgmt/tm/ltm/data-group"

}},{

"reference": {"link": "https://localhost/mgmt/tm/ltm/dns"

}},{

"reference": {"link": "https://localhost/mgmt/tm/ltm/global-settings"

}},{

"reference": {"link": "https://localhost/mgmt/tm/ltm/html-rule"

}},{

"reference": {"link": "https://localhost/mgmt/tm/ltm/monitor"

}},{

"reference": {"link": "https://localhost/mgmt/tm/ltm/persistence"

}},

http://www.json.org/

http://www.ietf.org/rfc/rfc4627.txt

{"reference": {

"link": "https://localhost/mgmt/tm/ltm/profile"}

},{

"reference": {"link": "https://localhost/mgmt/tm/ltm/default-node-monitor"

}},{

"reference": {"link": "https://localhost/mgmt/tm/ltm/ifile"

}},{

"reference": {"link": "https://localhost/mgmt/tm/ltm/nat"

}},{

"reference": {"link": "https://localhost/mgmt/tm/ltm/node"

}},{

"reference": {"link": "https://localhost/mgmt/tm/ltm/policy"

}},{

"reference": {"link": "https://localhost/mgmt/tm/ltm/policy-strategy"

}},{

"reference": {"link": "https://localhost/mgmt/tm/ltm/pool"

}},{

"reference": {"link": "https://localhost/mgmt/tm/ltm/rule"

}},{

"reference": {"link": "https://localhost/mgmt/tm/ltm/snat"

}},{

"reference": {"link": "https://localhost/mgmt/tm/ltm/snat-translation"

}},{

"reference": {"link": "https://localhost/mgmt/tm/ltm/snatpool"

}},{

"reference": {"link": "https://localhost/mgmt/tm/ltm/traffic-class"

}},{

"reference": {"link": "https://localhost/mgmt/tm/ltm/virtual"

}

12


},{

"reference": {"link": "https://localhost/mgmt/tm/ltm/virtual-address"

}}

],"kind": "tm:ltm:ltmstate","pageIndex": 1,"partition": "/Common/","selfLink": "https://localhost/mgmt/tm/ltm","startIndex": 1,"totalItems": 22,"totalPages": 1

}

Note: The JSON return from curl is on a single line; line breaks were added above for clarity. This partof the curl command uses an available Python script to format the output: |python -m json.tool Thejson.tool option is new in Python 2.6. The remaining examples also use this formatting technique.

This JSON return contains the following properties:

1. The first two items appear if this JSON object is a collection (a module is always a collection of tmshcomponents and sub-modules):

a. currentItemCount is the number of items in the collection, andb. items contains all the items in the collection. Each item contains a single reference with a single

link.

A link is the REST URI you can use to access details about this sub module or component. Youmust substitute the IP address for your BIG-IP device where localhost appears in this URI.

2. kind is the full path to the current module or component, where tm (an abbreviation for trafficmanagement) is always the root, and where colon (:) characters separate modules from sub-modulesand components.

3. partition is the administrative partition where this configuration object resides. Each partitioncorresponds to one folder, or tree of folders, where its configuration objects are stored. In tmsh, thepartition and its folder is invoked as a sys folder. By default, any call accesses the /Common partition.

4. The remaining options are relevant to paginating large outputs.

About JSON format for components

When you query a specific iControl® REST component (as opposed to a module), additional propertiesappear in the JSON objects that describe the component's configuration. These properties equate to theoutput from the tmsh list command. For example, this curl command focuses on the sys softwareimage component:

juser@bench2:~/$ curl -k -u admin:admin -H "Content-Type: \application/json" -X GET \https://192.168.25.42/mgmt/tm/sys/software/image \|python -m json.tool


{

13


"build": "2047.0","buildDate": "\"Sat Apr 6 14 54 06 PDT 2013\"","checksum": "7ea97e30cd95fd679248ce0678c542f3","fileSize": "\"1550 MB\"","generation": 0,"kind": "tm:sys:software:image:imagestate","lastModified": "\"Sat Apr 6 16:26:38 2013\"","lastUpdatedMicros": 0,"name": "BIGIP-11.4.0.2047.0.iso","product": "BIG-IP","selfLink":

"https://localhost/mgmt/tm/sys/software/image/BIGIP-11.4.0.2047.0.iso","verified": "yes","version": "11.4.0"

},{

"build": "2020.0","buildDate": "\"Thu Apr 4 10 00 48 PDT 2013\"","checksum": "7e22e9d391adc3822df1acf17e5408d8","fileSize": "\"1551 MB\"","generation": 0,"kind": "tm:sys:software:image:imagestate","lastModified": "\"Thu Apr 4 15:42:38 2013\"","lastUpdatedMicros": 0,"name": "BIGIP-11.4.0.2020.0.iso","product": "BIG-IP","selfLink":


},{

"build": "1989.0","buildDate": "\"Tue Apr 2 11 39 16 PDT 2013\"","checksum": "2a5885cc4ddbeacd0d1c156c70dbcd1c","fileSize": "\"1549 MB\"","generation": 0,"kind": "tm:sys:software:image:imagestate","lastModified": "\"Tue Apr 2 14:23:55 2013\"","lastUpdatedMicros": 0,"name": "BIGIP-11.4.0.1989.0.iso","product": "BIG-IP","selfLink":


},{

"build": "1927.0","buildDate": "\"Thu Mar 28 11 25 10 PDT 2013\"","checksum": "0994b173d4264dfb745e7c50b22f1f9d","fileSize": "\"1555 MB\"","generation": 0,"kind": "tm:sys:software:image:imagestate","lastModified": "\"Thu Mar 28 14:28:01 2013\"","lastUpdatedMicros": 0,"name": "BIGIP-11.4.0.1927.0.iso","product": "BIG-IP","selfLink":


}],"kind": "tm:sys:software:image:imagestate","pageIndex": 1,"partition": "/Common/","selfLink": "https://localhost/mgmt/tm/sys/software/image","startIndex": 1,

14


"totalItems": 4,"totalPages": 1

}

The properties in this output equate to the output from a similar tmsh list command. This example showsthe tmsh output for the sys software image component:

root@(BIG-IP1)(...)(tmos)# list sys software imagesys software image BIGIP-11.4.0.321.0.iso {

build 321.0build-date "Mon Feb 11 07 23 24 PST 2013"checksum f9411fde01d6a3521d4ae393e9bb077cfile-size "1522 MB"last-modified "Mon Feb 11 09:35:50 2013"product BIG-IPverified yesversion 11.4.0

}root@(BIG-IP1)(...)(tmos)#

About name formatting in iControl REST JSON and tmsh

The tmsh process uses a lowercase, dash-separated notation for its property and option names (such asalpha-beta-gamma), whereas the JSON notation for iControl® REST expresses the same names with aninitial lowercase character, no dashes, and an initial-uppercase character for every word after the first one(such as alphaBetaGamma).

For example, this property in tmsh,

build-date

becomes this in the JSON from iControl REST:

buildDate

About null values for flags

A flag is part of a tmsh component that either exists or does not exist, and has no particular value. All JSONproperties require a name and value pair, and tmsh flags always have a value. Therefore, iControl® RESTreturns all flags that are raised with the flag name and a value of null. If a flag is absent, iControl RESTomits the flag from the JSON output.

For example, this curl command shows all of the sys software volume components on the BIG-IPsystem at 192.168.25.42. The active property is a flag in the volume component; it appears as nullin the volume that is active, and does not appear at all in either of the other volumes:

juser@bench2:~/$ curl -k -u admin:admin -H "Content-Type: \application/json" -X GET \https://192.168.25.42/mgmt/tm/sys/software/volume \|python -m json.tool


15


{"active": null,"apiRawValues": {},"basebuild": "2047.0","build": "2047.0","generation": 0,"kind": "tm:sys:software:volume:volumestate","lastUpdatedMicros": 0,"media": [

{"defaultBootLocation": null,"media": "hd","name": "HD1.2","size": "default"

}],"name": "HD1.2","product": "BIG-IP",

"selfLink": "https://localhost/mgmt/tm/sys/software/volume/HD1.2",

"status": "complete","version": "11.4.0"

},{

"generation": 0,"kind": "tm:sys:software:volume:volumestate","lastUpdatedMicros": 0,"media": [

{"media": "hd","name": "HD1.1","size": "default"

}],"name": "HD1.1",


"status": "complete"},{

"basebuild": "2020.0","build": "2020.0","generation": 0,"kind": "tm:sys:software:volume:volumestate","lastUpdatedMicros": 0,"media": [

{"media": "hd","name": "HD1.3","size": "default"

}],"name": "HD1.3","product": "BIG-IP",


"status": "complete","version": "11.4.0"

}],"kind": "tm:sys:software:volume:volumestate","pageIndex": 1,"partition": "/Common/","selfLink": "https://localhost/mgmt/tm/sys/software/volume","startIndex": 1,"totalItems": 3,"totalPages": 1

}

16


Flags of this form are uncommon. Most have two or more values, such as enabled and disabled.

To POST or PUT a flag with only a single value, enter the property name in the JSON body with a valueof an empty string ("") or null. Omit the property name from objects that should have the flag lowered.

About names that differ from their tmsh counterparts

The iControl® REST process reserves several property names, including name and generation. In sometmsh components there are properties with the same name. In those cases, the JSON body contains tmshNameor tmshGeneration in place of their counterparts. For example, this GET produces output with tmshNamewhere name would appear in tmsh:

juser@bench2:~/$ curl -k -u admin:admin -H "Content-Type: \application/json" -X GET \https://192.168.25.42/mgmt/tm/ltm/dns/cache/resolver/resolver2 \|python -m json.tool

{"allowedQueryTime": 200,"answerDefaultZones": "no","generation": 0,"kind": "tm:ltm:dns:cache:resolver:resolverstate","lastUpdatedMicros": 0,"localZones": [

{"tmshName": "\"zone 1\"","type": "deny"

}],"maxConcurrentQueries": 1024,"maxConcurrentTcp": 20,"maxConcurrentUdp": 8192,"msgCacheSize": 1048576,"name": "resolver2","nameserverCacheCount": 16536,"partition": "/Common/","randomizeQueryNameCase": "yes","routeDomain": "0","rrsetCacheSize": 10485760,"selfLink": "https://localhost/mgmt/tm/ltm/dns/cache/resolver/resolver2",

"unwantedQueryReplyThreshold": 0,"useIpv4": "yes","useIpv6": "yes","useTcp": "yes","useUdp": "yes"

}

About JSON format for POST and PUT

Use JSON format to define an object's configuration in all POST and PUTmethods. This is the same formatused for all GET returns. A POST creates a new configuration object, and a PUT edits an existingconfiguration object. You define the name to identify the configuration object. Then you include thenon-default parameters for the object, using the same options and properties that you find from a similarobject's GET. Any properties you omit revert to what was already set (in the case of a PUT) or their a PUTedits an existing configuration object.

17


You must declare the format of the object you are posting in your REST call. For iControl REST, the formatis always JSON. In a curl command, for example, you use -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, you define the "name" to identify the configuration object. Then you include thenon-default parameters for the object, using the same options and properties that you find from a similarobject's GET. Any properties you omit revert to what was already set (in the case of a PUT) or their defaults(in the case of a POST).

The URI specifies the container to hold the object that you POST, or the object that you edit with PUT.

18


Discovering all modules and components in iControl REST

The iControl® REST service supports a subset of over 600 components existing in tmsh. You can use theTraffic Management Shell (tmsh) Reference to find all possible tmsh modules and components, most ofwhich appear under the same names in tmsh, or you can use this procedure to automatically discover thecontents of each top-level module.

1. Identify all of the root modules in tmsh that are supported by iControl REST. iControl REST supportsthe following root modules from tmsh:

• apm

• cm

• gtm

• ltm

• net

• sys

2. Use curl (or a similar utility) to query iControl REST on your BIG-IP system. You can request anyroot module from the previous list. For example, this call queries the device at 192.168.25.42 for thecontents of the ltm module:

juser@bench2:~/$ curl -k -u admin:admin -H "Content-Type: \application/json" -X GET \https://192.168.25.42/mgmt/tm/ltm \|python -m json.tool


{"reference": {

"link": "https://localhost/mgmt/tm/ltm/auth"}

},{

"reference": {"link": "https://localhost/mgmt/tm/ltm/data-group"

}},{

"reference": {"link": "https://localhost/mgmt/tm/ltm/dns"

}},{

"reference": {"link": "https://localhost/mgmt/tm/ltm/global-settings"

}},{

"reference": {"link": "https://localhost/mgmt/tm/ltm/html-rule"

}},{

"reference": {"link": "https://localhost/mgmt/tm/ltm/monitor"

}},

{"reference": {

"link": "https://localhost/mgmt/tm/ltm/persistence"}

},{

"reference": {"link": "https://localhost/mgmt/tm/ltm/profile"

}},{

"reference": {"link": "https://localhost/mgmt/tm/ltm/default-node-monitor"

}},{

"reference": {"link": "https://localhost/mgmt/tm/ltm/ifile"

}},{

"reference": {"link": "https://localhost/mgmt/tm/ltm/nat"

}},{

"reference": {"link": "https://localhost/mgmt/tm/ltm/node"

}},{

"reference": {"link": "https://localhost/mgmt/tm/ltm/policy"

}},{

"reference": {"link": "https://localhost/mgmt/tm/ltm/policy-strategy"

}},{

"reference": {"link": "https://localhost/mgmt/tm/ltm/pool"

}},{

"reference": {"link": "https://localhost/mgmt/tm/ltm/rule"

}},{

"reference": {"link": "https://localhost/mgmt/tm/ltm/snat"

}},{

"reference": {"link": "https://localhost/mgmt/tm/ltm/snat-translation"

}},{

"reference": {"link": "https://localhost/mgmt/tm/ltm/snatpool"

}},{

"reference": {"link": "https://localhost/mgmt/tm/ltm/traffic-class"

20


}},{

"reference": {"link": "https://localhost/mgmt/tm/ltm/virtual"

}},{

"reference": {"link": "https://localhost/mgmt/tm/ltm/virtual-address"

}}

],"kind": "tm:ltm:ltmstate","pageIndex": 1,"partition": "/Common/","selfLink": "https://localhost/mgmt/tm/ltm","startIndex": 1,"totalItems": 22,"totalPages": 1

}

You can use the URI in any link property to learn about the sub-module or component; replacelocalhost in the link with the IP address or FQDN for your BIG-IP® device.

3. Query iControl REST again, this time for the lower-level module or component. In this example, thecall queries the same device with the persistence link from the previous output:

juser@bench2:~/$ curl -k -u admin:admin -H "Content-Type: \application/json" -X GET \https://192.168.25.42/mgmt/tm/ltm/persistence \|python -m json.tool


{"reference": {

"link": "https://localhost/mgmt/tm/ltm/persistence/cookie"}

},{

"reference": {"link": "https://localhost/mgmt/tm/ltm/persistence/dest-addr"

}},{

"reference": {"link":

"https://localhost/mgmt/tm/ltm/persistence/global-settings"}

},{

"reference": {"link": "https://localhost/mgmt/tm/ltm/persistence/hash"

}},{

"reference": {"link": "https://localhost/mgmt/tm/ltm/persistence/msrdp"

}},{

"reference": {"link": "https://localhost/mgmt/tm/ltm/persistence/sip"

}},

21


{"reference": {

"link":"https://localhost/mgmt/tm/ltm/persistence/source-addr"

}},{

"reference": {"link": "https://localhost/mgmt/tm/ltm/persistence/ssl"

}},{

"reference": {"link": "https://localhost/mgmt/tm/ltm/persistence/universal"

}}

],"kind": "tm:ltm:persistence:persistencestate","pageIndex": 1,"partition": "/Common/","selfLink": "https://localhost/mgmt/tm/ltm/persistence","startIndex": 1,"totalItems": 9,"totalPages": 1

}

Continuing with the example, this query discovers the contents of the global-settings component:

juser@bench2:~/$ curl -k -u admin:admin -H "Content-Type: \application/json" -X GET \https://192.168.25.42/mgmt/tm/ltm/persistence/global-settings \|python -m json.tool

{"destAddrLimitMode": "timeout","destAddrMax": 2048,"kind": "tm:ltm:persistence:global-settings:global-settingsstate","partition": "/Common/","proxyGroup": "/Common/aol","selfLink": "https://localhost/mgmt/tm/ltm/persistence/global-settings"

}

This output shows the full configuration of the global-settings component.

You can use this method to discover the entire iControl-REST interface.

Note: The contents of an iControl-REST component may not have all of the properties and options of itstmsh counterpart below the sub-collection level.

Paging through large collections

Some collections have very large numbers of items and would use a great deal of bandwidth and processingpower if taken in a single GET request.

1. Use the $top query option at the end of the URI to set the maximum number of items for the BIG-IP®

device to return. If you invoke this from a Unix command line, precede the dollar sign character ($)with a backslash character (\) to prevent misinterpretation.

22


https://uri?\$top=n

Where:

• uri identifies the resource (for example, 192.168.25.42/mgmt/tm/ltm), and• n is the maximum number of items to return.

For example, this command returns only four items from the collection of components and sub-modulesin the sys module:

juser@bench2:~/$ curl -k -u admin:admin -H "Content-Type: \application/json" -X GET \https://192.168.25.42/mgmt/tm/sys?\$top=4 \|python -m json.tool


{"reference": {

"link": "https://localhost/mgmt/tm/sys/application"}

},{

"reference": {"link": "https://localhost/mgmt/tm/sys/crypto"

}},{

"reference": {"link": "https://localhost/mgmt/tm/sys/daemon-log-settings"

}},{

"reference": {"link": "https://localhost/mgmt/tm/sys/disk"

}}

],"itemsPerPage": 4,"kind": "tm:sys:sysstate","nextLink": "https://localhost/mgmt/tm/sys?$top=4&$skip=4","pageIndex": 1,"partition": "/Common/","selfLink": "https://localhost/mgmt/tm/sys?$top=4","startIndex": 1,"totalItems": 34,"totalPages": 9

}

The JSON returns these parameters to help with pagination:

• currentItemCount is the number of items in this return,• itemsPerPage matches the number you chose with the $top query option,• pageIndex and totalPages show your position in the set of pages,• startIndex and totalItems show your position in the overall collection, and• previousLink, selfLink, and nextLink are URIs that you can use to navigate to the previous

page, the current page (where you are now), and the next page. You need to substitute the actualmanagement address for your BIG-IP device in place of localhost.

2. Use the $skip option (after the $top option) to skip over all the items in previous returns. As withother query parameters, youmust escape the dollar sign character ($) with a preceding backslash character(\) on a Unix command line.

23


https://uri?\$top=n\&\$skip=m

Where:

• uri identifies the resource (for example, 192.168.25.42/mgmt/tm/ltm),• the backslash character (\) before the dollar sign ($) and ampersand (&) is only required for a Unix

shell, to escape those special characters,• n is the maximum number of items to return on this page, and• m is the number of previously-received items to skip.

For example, this command returns the next four items from the sys module:

juser@bench2:~/$ curl -k -u admin:admin -H "Content-Type: \application/json" -X GET \https://192.168.25.42/mgmt/tm/sys?\$top=4\&\$skip=4 \|python -m json.tool


{"reference": {

"link": "https://localhost/mgmt/tm/sys/file"}

},{

"reference": {"link": "https://localhost/mgmt/tm/sys/icall"

}},{

"reference": {"link": "https://localhost/mgmt/tm/sys/log-config"

}},{

"reference": {"link": "https://localhost/mgmt/tm/sys/sflow"

}}

],"itemsPerPage": 4,"kind": "tm:sys:sysstate","nextLink": "https://localhost/mgmt/tm/sys?$top=4&$skip=8","pageIndex": 2,"partition": "/Common/","previousLink": "https://localhost/mgmt/tm/sys?$top=4","selfLink": "https://localhost/mgmt/tm/sys?$top=4&$skip=4","startIndex": 5,"totalItems": 34,"totalPages": 9

}

Expanding iControl-REST component links

Some components contain links to sub-components or members. The details of those sub-components areunknown unless you do another GET for each of the sub-components, or unless you use the $expand queryoption. The $expand query option functions on components only; it has no effect on module queries.

24


To see all the details of a particular component, including the details of its sub-components, use the$expand query option at the end of the URL. From a Unix command line, you must precede the dollarsign ($) with a backslash character (\), to prevent misinterpretation of the command.

https://uri?\$expand=*

Where uri identifies the resource (for example, 192.168.25.42/mgmt/tm/ltm).

For example, this iControl®-REST call shows the non-expanded view of an LTM® pool namedtest-pool2:

juser@bench2:~/$ curl -k -u admin:admin -H "Content-Type: \application/json" -X GET \https://192.168.25.42/mgmt/tm/ltm/pool/test-pool2 \|python -m json.tool

{"allowNat": "yes","allowSnat": "yes","generation": 0,"ignorePersistedWeight": "disabled","ipTosToClient": "pass-through","ipTosToServer": "pass-through","kind": "tm:ltm:pool:poolstate","lastUpdatedMicros": 0,"linkQosToClient": "pass-through","linkQosToServer": "pass-through","loadBalancingMode": "round-robin","membersReference": {

"link": "https://localhost/mgmt/tm/ltm/pool/test-pool2/members"},"minActiveMembers": 0,"minUpMembers": 0,"minUpMembersAction": "failover","minUpMembersChecking": "disabled","name": "test-pool2","partition": "/Common/","queueDepthLimit": 0,"queueOnConnectionLimit": "disabled","queueTimeLimit": 0,"reselectTries": 0,"selfLink": "https://localhost/mgmt/tm/ltm/pool/test-pool2","slowRampTime": 10

}

No details appear for any of the pool members.

This next example expands the output to show full details for all members of the pool:

juser@bench2:~/$ curl -k -u admin:admin -H "Content-Type: \application/json" -X GET \https://192.168.25.42/mgmt/tm/ltm/pool/test-pool2?\$expand=* \|python -m json.tool

{"allowNat": "yes","allowSnat": "yes","generation": 0,"ignorePersistedWeight": "disabled","ipTosToClient": "pass-through","ipTosToServer": "pass-through","kind": "tm:ltm:pool:poolstate","lastUpdatedMicros": 0,"linkQosToClient": "pass-through","linkQosToServer": "pass-through","loadBalancingMode": "round-robin","members": [

{

25


"address": "192.168.25.44","connectionLimit": 0,"dynamicRatio": 1,"generation": 0,"inheritProfile": "enabled","kind": "tm:ltm:pool:members:membersstate","lastUpdatedMicros": 0,"monitor": "default","name": "192.168.25.44:http","priorityGroup": 0,"rateLimit": "disabled","ratio": 1,"selfLink":

"https://localhost/mgmt/tm/ltm/pool/test-pool2/members/192.168.25.44:http",

"session": "user-enabled","state": "unchecked"

},{




},{




}],"minActiveMembers": 0,"minUpMembers": 0,"minUpMembersAction": "failover","minUpMembersChecking": "disabled","name": "test-pool2","partition": "/Common/","queueDepthLimit": 0,"queueOnConnectionLimit": "disabled","queueTimeLimit": 0,"reselectTries": 0,"selfLink": "https://localhost/mgmt/tm/ltm/pool/test-pool2?$expand=*",

26


"slowRampTime": 10}

Understanding iControl REST expansion

Configuration components can contain properties, child components, and associated (non-child) components.You can create an associated component independently from the component that contains it; for example,a virtual server (the ltm virtual component in tmsh) can contain an LTM® pool, but you create the LTMpool separately.

The iControl® $expand query option displays all child components but does not include any associated(non-child) components.

For example, the following curl command shows the expanded view of a virtual server with an LTM pool,http-pool5. The pool property is not expanded, but the profiles property is:

juser@bench2:~/$ curl -k -u admin:admin -H "Content-Type: \application/json" -X GET \https://192.168.25.42/mgmt/tm/ltm/virtual/vs4?\$expand=* \|python -m json.tool

{"autoLasthop": "default","cmpEnabled": "yes","connectionLimit": 0,"description": "\"fourth server\"","destination": "0.0.0.0:any","enabled": null,"generation": 0,"gtmScore": 0,"ipProtocol": "any","kind": "tm:ltm:virtual:virtualstate","lastUpdatedMicros": 0,"mask": "any","mirror": "disabled","name": "vs4","nat64": "disabled","partition": "/Common/","pool": "http-pool5","profiles": [

{"context": "all","generation": 0,"kind": "tm:ltm:virtual:profiles:profilesstate","lastUpdatedMicros": 0,"name": "fastL4","selfLink":

"https://localhost/mgmt/tm/ltm/virtual/vs4/profiles/fastL4"}

],"rateLimit": "disabled","rateLimitDstMask": 0,"rateLimitMode": "object","rateLimitSrcMask": 0,"selfLink": "https://localhost/mgmt/tm/ltm/virtual/vs4?$expand=*","source": "0.0.0.0/0","sourceAddressTranslation": {},"sourcePort": "preserve","synCookieStatus": "not-activated","translateAddress": "disabled","translatePort": "disabled","vlansDisabled": null,

27


"vsIndex": 8}

Accessing an administrative partition or folder

An administrative partition is a part of the BIG-IP® configuration that is only accessible to a particular groupof administrators. The default partition for all BIG-IP configurations, /Common, is accessible to alladministrators. A sufficiently-privileged administrator can make additional partitions. By default, alliControl-REST calls access the configuration in /Common. You use the $partition query option to accessthe configuration in a different partition. Each partition has a corresponding sys folder in tmsh andsys/folder in an iControl REST URI. Folders can be nested, such as /folder1/folder2/folder3,but only top-level folders, such as /folder1, correspond to partitions.

To access a partition or sub-folder other than /Common, use the $partition query option at the endof the URL. You must use the credentials of an administrator with permission to access the chosenpartition. If you invoke the URI from a Unix command like curl, use a backslash character (\) beforethe dollar sign character ($).

https://uri?\$partition=/partition-name

Where:

• uri identifies the resource (for example, 192.168.25.42/mgmt/tm/ltm), and• /partition-name is the partition or sub-folder. You must precede the partition/folder name with

a forward slash character (/).

For example, this iControl® REST call gets the LTM® pools from the /dns_config partition:

juser@bench2:~/$ curl -k -u admin:admin -H "Content-Type: \application/json" -X GET \https://192.168.25.42/mgmt/tm/ltm/pool?\$partition=/dns_config \|python -m json.tool



"link":"https://localhost/mgmt/tm/ltm/pool/dns-pool/members?$partition=/dns_config/"

},"minActiveMembers": 0,"minUpMembers": 0,"minUpMembersAction": "failover","minUpMembersChecking": "disabled","name": "dns-pool","queueDepthLimit": 0,"queueOnConnectionLimit": "disabled",

28


"queueTimeLimit": 0,"reselectTries": 0,"selfLink":

"https://localhost/mgmt/tm/ltm/pool/dns-pool?$partition=/dns_config/","slowRampTime": 10

},{

"allowNat": "yes","allowSnat": "yes","generation": 0,"ignorePersistedWeight": "disabled","ipTosToClient": "pass-through","ipTosToServer": "pass-through","kind": "tm:ltm:pool:poolstate","lastUpdatedMicros": 0,"linkQosToClient": "pass-through","linkQosToServer": "pass-through","loadBalancingMode": "round-robin","membersReference": {

"link":"https://localhost/mgmt/tm/ltm/pool/dns-pool2/members?$partition=/dns_config/"

},"minActiveMembers": 0,"minUpMembers": 0,"minUpMembersAction": "failover","minUpMembersChecking": "disabled","name": "dns-pool2","queueDepthLimit": 0,"queueOnConnectionLimit": "disabled","queueTimeLimit": 0,"reselectTries": 0,"selfLink":

"https://localhost/mgmt/tm/ltm/pool/dns-pool2?$partition=/dns_config/","slowRampTime": 10

}],"kind": "tm:ltm:pool:poolstate","pageIndex": 1,"partition": "/dns_config/","selfLink": "https://localhost/mgmt/tm/ltm/pool?$partition=/dns_config",

"startIndex": 1,"totalItems": 2,"totalPages": 1

}

Getting Show content instead of List content

The iControl®REST service returns JSON-formatted representations of the tmsh list command; however,you might prefer statistical information from the equivalent of the tmsh show command instead.

Append "?$stats=true" to the end of the URI to receive the equivalent of the tmsh show command.If you invoke the URI from a Unix command (such as curl), use a backslash character (\) before thedollar sign ($).https://management-ip/mgmt/tm/module[/sub-module]/component?\$stats=true

29


For example, this curl command shows an LTM® pool with the content of a show command:

juser@bench2:~/$ curl -k -u admin:admin -H "Content-Type: \application/json" -X GET \https://192.168.25.42/mgmt/tm/ltm/pool/test-pool2?\$stats=true \|python -m json.tool

{"activeMemberCnt": 0,"connq": {

"ageEdm": 0,"ageEma": 0,"ageHead": 0,"ageMax": 0,"depth": 0,"serviced": 0

},"connqAll": {

"ageEdm": 0,"ageEma": 0,"ageHead": 0,"ageMax": 0,"depth": 0,"serviced": 0

},"curSessions": 0,"generation": 0,"kind": "tm:ltm:pool:poolstats","lastUpdatedMicros": 0,"minActiveMembers": 0,"monitorRule": "none","name": "test-pool2","partition": "/Common/","selfLink": "https://localhost/mgmt/tm/ltm/pool/test-pool2?$stats=true",

"serverside": {"bitsIn": 0,"bitsOut": 0,"curConns": 0,"maxConns": 0,"pktsIn": 0,"pktsOut": 0,"totConns": 0

},"status": {

"availabilityState": "unknown","enabledState": "enabled",

"statusReason": "The children pool member(s) either don't have servicechecking enabled, or service check results are not available yet"

},"tmshName": "test-pool2","totRequests": 0

}

The previous JSON output is equivalent to this show command in tmsh:

root@(BIG-IP1)(...)(tmos)# show ltm pool test-pool2

---------------------------------------------------------------------Ltm::Pool: test-pool2---------------------------------------------------------------------StatusAvailability : unknownState : enabledReason : The children pool member(s) either don't have service

checking enabled, or service check results are not available yetMonitor : none

30


Minimum Active Members : 0Current Active Members : 0

Total Requests : 0Current Sessions : 0

Traffic ServerSideBits In 0Bits Out 0Packets In 0Packets Out 0Current Connections 0Maximum Connections 0Total Connections 0

Connection Queue Pool Pool and membersNumber of connections queued now 0 0Number of connections serviced 0 0Queue head entry age (ms) 0 0Maximum queue entry age ever (ms) 0 0Maximum queue entry age recently (ms) 0 0Average queue entry age (ms) 0 0

root@(BIG-IP1)(...)(tmos)#

31


32


Adding new configurations

Through iControl®REST, you can use the POSTmethod to change the configuration of the BIG-IP® system.The POST method acts on the URI for a collection of configuration objects, and it adds a new object to thecollection. You define the new object using JSON format; include the name property (to provide a namefor the new object) and all other properties that should deviate from their defaults. iControl REST sets allother properties to their defaults.

Use the HTTPS POST method to add a new configuration object to a collection in the BIG-IPconfiguration. In this example, the curl command creates a new LTM® pool object in the ltm/poolcollection. The new object is named http-pool and it contains three members. Each member alsocontains a description. (Note that iControl REST assigns default values to all properties not included inthe JSON input.) The iControl REST service responds with the full result in JSON format.

juser@bench2:~/$ curl -k -u admin:admin -H "Content-Type: \application/json" -X POST -d \'{"name":"http-pool","members":[ \{"name":"192.168.25.32:80","description":"member1"}, \{"name":"192.168.25.33:80","description":"member2"}, \{"name":"192.168.25.34:80","description":"member3"}]}' \https://192.168.25.42/mgmt/tm/ltm/pool \|python -m json.tool


"link": "https://localhost/mgmt/tm/ltm/pool/http-pool/members"},"minActiveMembers": 0,"minUpMembers": 0,"minUpMembersAction": "failover","minUpMembersChecking": "disabled","name": "http-pool","partition": "/Common/","queueDepthLimit": 0,"queueOnConnectionLimit": "disabled","queueTimeLimit": 0,"reselectTries": 0,"selfLink": "https://localhost/mgmt/tm/ltm/pool/http-pool","slowRampTime": 10

}

The return value is the same information you would receive from a GET of the new LTM® pool,https://192.168.25.42/mgmt/tm/ltm/pool/http-pool.

Modifying a configuration object

You can use the PUT method to change one or more properties in a configuration object without affectingany other properties.

To do this, call out the configuration object itself, not the collection, in the URI, and specify the propertiesyou want to change in the JSON body. For example, this command changes two parameters for aparticular LTM® pool, and then returns the pool configuration (after the change); note the changedproperties in the return text, as shown here.

juser@bench2:~/$ curl -k -u admin:admin -H "Content-Type: \application/json" -X PUT -d \'{"name":"http-pool","description":"backup web \servers","ignorePersistedWeight": "enabled"}' \https://192.168.25.42/mgmt/tm/ltm/pool/http-pool \|python -m json.tool

{"allowNat": "yes","allowSnat": "yes","description": "\"backup web servers\"","generation": 0,"ignorePersistedWeight": "enabled","ipTosToClient": "pass-through","ipTosToServer": "pass-through","kind": "tm:ltm:pool:poolstate","lastUpdatedMicros": 0,"linkQosToClient": "pass-through","linkQosToServer": "pass-through","loadBalancingMode": "round-robin","membersReference": {


}

The PUT method alters specific properties of an iControl®-REST component.

Modifying a collection

Some configuration objects contain collections, denoted by square brackets ([]) in JSON format. For example,an LTM® pool has a collection of member objects, and a rule-list (in the security firewallmodule)has a collection of rule objects. When you edit one of these collections with the PUT method, only theobjects that you include in your JSON input are included in the final collection. Therefore, if you PUT onemember object into an LTM pool that originally had three members, the PUT reduces the pool to the singlemember.

34


1. Include all required objects in any collection that you edit with PUT. In this example, the curl commandPUTs three member objects into an LTM pool with small changes to each of their configurations. Thecurl command specifies only the properties that need to change in each member object.

juser@bench2:~/$ curl -k -u admin:admin -H "Content-Type: \application/json" -X PUT -d \'{"name":"http-pool","members":[ \{"name":"192.168.25.32:80","rateLimit": "1"}, \{"name":"192.168.25.33:80","description":"member2, \table 6"},{"name":"192.168.25.34:80","rateLimit": \"1","description":"member3, table 6"}]}' \https://192.168.25.42/mgmt/tm/ltm/pool/http-pool \|python -m json.tool

{"allowNat": "yes","allowSnat": "yes","description": "\"backup web servers\"","generation": 0,"ignorePersistedWeight": "enabled","ipTosToClient": "pass-through","ipTosToServer": "pass-through","kind": "tm:ltm:pool:poolstate","lastUpdatedMicros": 0,"linkQosToClient": "pass-through","linkQosToServer": "pass-through","loadBalancingMode": "round-robin","membersReference": {


}

2. To verify your change for a particular member, use the value of the membersReference's link propertyin a GET request. For example, this verifies that iControl® REST successfully saved all the changesfrom the previous example:

juser@bench2:~/$ curl -k -u admin:admin -H "Content-Type: \application/json" -X GET \https://192.168.25.42/mgmt/tm/ltm/pool/http-pool/members \|python -m json.tool


{"address": "192.168.25.32","connectionLimit": 0,"dynamicRatio": 1,"generation": 0,"inheritProfile": "enabled","kind": "tm:ltm:pool:members:membersstate","lastUpdatedMicros": 0,"monitor": "default","name": "192.168.25.32:http","priorityGroup": 0,

35


"rateLimit": "1","ratio": 1,"selfLink":

"https://localhost/mgmt/tm/ltm/pool/http-pool/members/192.168.25.32:http",


},{

"address": "192.168.25.33","connectionLimit": 0,"description": "\"member2, table 6\"","dynamicRatio": 1,"generation": 0,"inheritProfile": "enabled","kind": "tm:ltm:pool:members:membersstate","lastUpdatedMicros": 0,"monitor": "default","name": "192.168.25.33:http","priorityGroup": 0,"rateLimit": "disabled","ratio": 1,"selfLink":



},{

"address": "192.168.25.34","connectionLimit": 0,"description": "\"member3, table 6\"","dynamicRatio": 1,"generation": 0,"inheritProfile": "enabled","kind": "tm:ltm:pool:members:membersstate","lastUpdatedMicros": 0,"monitor": "default","name": "192.168.25.34:http","priorityGroup": 0,"rateLimit": "1","ratio": 1,"selfLink":



}],"kind": "tm:ltm:pool:members:membersstate","pageIndex": 1,"partition": "/Common/","selfLink": "https://localhost/mgmt/tm/ltm/pool/http-pool/members","startIndex": 1,"totalItems": 3,"totalPages": 1

}

You can also use the $expand=* query option in the PUT call. This causes the return from the PUT toexpand all sub-collections.

36


Modifying a single object in a collection

Some sub-collections allow direct access to individual items, so that calling out all members of the collection(as described inModifying a collection) is not required. The sub-collections that allow direct access appearin the Public URIs section.

Use the public URI to access an individual item inside a collection.

For example, this uses the public URI at /mgmt/tm/ltm/pool/members to update the description fora single member in the LTM® pool named http-pool:

juser@bench2:~/$ curl -k -u admin:admin -H "Content-Type: \application/json" -X PUT -d '{"description": "member 8 \on table 12"}' \https://192.168.25.42/mgmt/tm/ltm/pool/http-pool/members/192.168.25.32:80

\|python -m json.tool

{"address": "192.168.25.32","connectionLimit": 0,"description": "\"member 8 on table 12\"","dynamicRatio": 1,"generation": 0,"inheritProfile": "enabled","kind": "tm:ltm:pool:members:membersstate","lastUpdatedMicros": 0,"monitor": "default","name": "192.168.25.32:80","partition": "/Common/","priorityGroup": 0,"rateLimit": "1","ratio": 1,"selfLink":

"https://localhost/mgmt/tm/ltm/pool/http-pool/members/192.168.25.32:80","session": "user-enabled","state": "unchecked"

}

Understanding how iControl REST manages read-only properties

If you include any read-only properties in a PUT or POST method, iControl® REST accepts the call butsilently ignores those property values. The PUT or POST succeeds, assuming it was otherwise valid andcomplete. For example, the following curl command PUTs two properties in an existing cm deviceobject: contact information, which is editable, and time-zone, which is read-only. The return fromiControl REST shows that the contact property changed but the time-zone property did not:

juser@bench2:~/$ curl -k -u admin:admin -H "Content-Type: \application/json" -X PUT -d \'{"contact":"jsmith","time-zone":"EDT"}' \https://192.168.25.42/mgmt/tm/cm/device/bigip1 \|python -m json.tool

{"activeModules": [

"BIG-IP, LAB (LTM,APM,ASM,GTM,WOM), VE|N743384-9628034|IPV6 Gateway|RateShaping|Ram Cache|50 Mbps Compression|SSL, 500 TPS Per Core|Client

37


Authentication|APM, Limited|ASM, VE|PSM, VE|WBA, VE|TCE, BIG-IP|SSL, ForwardProxy|Routing Bundle, VE|AFM, VE|WOM, VE|External Interface and NetworkHSM|DNS Services|Anti-Virus Checks|Base Endpoint Security Checks|FirewallChecks|Machine Certificate Checks|Network Access|Protected Workspace|SecureVirtual Keyboard|APM, Web Application|App Tunnel|Remote Desktop|Max Compression,VE|SSL, Max TPS, VE|DNS Rate Fallback, Unlimited|DNS Licensed Objects,Unlimited|DNS Rate Limit, Unlimited QPS|DNS RATE LIMITED, MAX",

"DNSSEC|S863486-2405211"],"baseMac": "0:50:56:88:6b:b0","build": "2047.0","cert": "dtdi.crt","chassisId": "42088d93-e8df-5955-bc77be1a25cc","chassisType": "individual","contact": "jsmith","edition": "Final","failoverState": "active","generation": 0,"haCapacity": 0,"hostname": "bigip1","key": "dtdi.key","kind": "tm:cm:device:devicestate","lastUpdatedMicros": 0,"managementIp": "192.168.25.42","marketingName": "\"BIG-IP Virtual Edition\"","mirrorIp": "any6","mirrorSecondaryIp": "any6","multicastIp": "any6","multicastPort": "any","name": "bigip1","optionalModules": [

"App Mode (TMSH Only, No Root/Bash)","Carrier Grade NAT, BIG-IP","EA Features"

],"partition": "/Common/","platformId": "Z100","product": "BIG-IP","selfDevice": "true","selfLink": "https://localhost/mgmt/tm/cm/device/bigip1","timeZone": "PDT","version": "11.4.0"

}

Adding or modifying in a partition

An administrative partition is a part of the BIG-IP® configuration that is only accessible to a particular groupof administrators. The default partition for all BIG-IP configurations, /Common, is accessible to alladministrators. A sufficiently-privileged administrator can make additional partitions. You can use the$partition query option to POST or PUT configuration objects in a partition, as you do with GET, oryou can use a property in the JSON body.

In a PUT operation, you have the option to identify the object's partition in the partition property.You do not need the $partition query option. For example, this command changes the descriptionfor an LTM® pool in the /dns_config partition:

juser@bench2:~/$ curl -k -u admin:admin -H "Content-Type: \application/json" -X PUT -d \'{"partition":"/dns_config","description":"DCs in the \central office"}' \

38


https://192.168.25.42/mgmt/tm/ltm/pool/dns-pool2 \|python -m json.tool

{"allowNat": "yes","allowSnat": "yes","description": "\"DCs in the central office\"","generation": 0,"ignorePersistedWeight": "disabled","ipTosToClient": "pass-through","ipTosToServer": "pass-through","kind": "tm:ltm:pool:poolstate","lastUpdatedMicros": 0,"linkQosToClient": "pass-through","linkQosToServer": "pass-through","loadBalancingMode": "round-robin","membersReference": {

"link":"https://localhost/mgmt/tm/ltm/pool/dns-pool2/members?$partition=/dns_config/"

},"minActiveMembers": 0,"minUpMembers": 0,"minUpMembersAction": "failover","minUpMembersChecking": "disabled","name": "dns-pool2","partition": "/dns_config/","queueDepthLimit": 0,"queueOnConnectionLimit": "disabled","queueTimeLimit": 0,"reselectTries": 0,"selfLink":

"https://localhost/mgmt/tm/ltm/pool/dns-pool2?$partition=/dns_config/","slowRampTime": 10

}

Important: The $partition query option and the partition property are equally valid methods foridentifying an administrative partition.

About relative partitions and folders

If you use relative folder paths within a partition body, iControl REST interprets them relative to the parentpartition. You set the parent's partition with the $partition query option or by setting the partitionproperty in the JSON body. For example, of the $partition query option is set to /eu and there is areference to the france folder in the JSON body, iControl® REST interprets the folder as /eu/france.You can use absolute paths for all folders in your JSON body (such as /eu/france) to avoid any ambiguity.

Adding an object with a forward slash character in its name

Some object names include forward slash characters (/), which could be confused with a partition or foldername if used in a POST operation.

1. In addition to specifying the name in the JSON body, add an apiDecoratedName with the forwardslash character (/). The name property is the name of the object, and the apiDecoratedName is thename that the BIG-IP® software creates from that name, which contains forward slashes. For example,

39


this post adds a sys application service, which takes a service-name and renames the serviceservice-name.app/service-name:

juser@bench2:~/$ curl -k -u admin:admin -H "Content-Type: \application/json" -X POST -d \'{"name":"service1","apiDecoratedName":"service1.app/service1"}' \https://192.168.25.42/mgmt/tm/sys/application/service \|python -m json.tool

{"deviceGroup": "none","generation": 0,"inheritedDevicegroup": "true","inheritedTrafficGroup": "true","kind": "tm:sys:application:service:servicestate","lastUpdatedMicros": 0,"name": "service1.app/service1","partition": "/Common/","selfLink":

"https://localhost/mgmt/tm/sys/application/service/service1.app~service1",

"strictUpdates": "disabled","templateModified": "no","trafficGroup": "traffic-group-1"

}

2. To retrieve the configuration with a GET, use the apiDecoratedNamewith tilde characters (~) in placeof each forward slash character (/). For example, this GET operation gets the previousapplication-service object:

juser@bench2:~/$ curl -k -u admin:admin -H "Content-Type: \application/json" -X GET \

https://192.168.25.42/mgmt/tm/sys/application/service/service1.app~service1\

|python -m json.tool{

"deviceGroup": "none","generation": 0,"inheritedDevicegroup": "true","inheritedTrafficGroup": "true","kind": "tm:sys:application:service:servicestate","lastUpdatedMicros": 0,"name": "service1.app/service1","partition": "/Common/","selfLink":

"https://localhost/mgmt/tm/sys/application/service/service1.app~service1",

"strictUpdates": "disabled","templateModified": "no","trafficGroup": "traffic-group-1"

}

Deleting a configuration object

You can use the HTTPDELETEmethod to remove a BIG-IP® system configuration object through iControl®

REST. You can only delete single configuration objects, not collections.

40


1. Use the GET method to confirm that the object you want to delete currently exists. For example, thisshows that an LTM® pool named test-pool2 currently exists:

juser@bench2:~/$ curl -k -u admin:admin -H "Content-Type: \application/json" -X GET \https://192.168.25.42/mgmt/tm/ltm/pool \|python -mjson.tool


{"allowNat": "yes","allowSnat": "yes","name": "http-pool2","appService": "none",

..."serviceDownAction": "none","slowRampTime": 10

},{

"allowNat": "yes","allowSnat": "yes","name": "test-pool2","appService": "none",

..."selfLink": "https://localhost/mgmt/tm/ltm/pool","startIndex": 1,"totalItems": 5,"totalPages": 1

}juser@bench2:~/$

2. Use the DELETE method on a component's URI to delete the component from the BIG-IP systemconfiguration. On a successful deletion, iControl REST returns no JSON response. For example, thisdeletes the test-pool2 pool:

juser@bench2:~/$ curl -k -u admin:admin -H "Content-Type: \application/json" -X DELETE \https://192.168.25.42/mgmt/tm/ltm/pool/test-pool2 \|python -m json.tool

Another GET call on https://192.168.25.42/mgmt/tm/ltm/pool would show the same poolsagain, but without test-pool2.

41


42


Adding a partition

An administrative partition is a part of the BIG-IP® configuration that is only accessible to a particular groupof administrators. The default partition for all BIG-IP configurations, /Common, is accessible to alladministrators. A sufficiently-privileged administrator canmake additional partitions. By default, all iControl®

REST changes occur in the configuration in /Common. Each partition corresponds to a folder (with the samename) to hold its configuration objects, accessible from tmsh as a sys folder and from an iControl-RESTURI as a sys/folder.

To create to a new partition/folder, POST it to the sys/folder module. Put the new folder name(including the leading slash (/) character) in the "name" property of the JSON body. For example, thisiControl REST call adds the /fw_objs partition to the BIG-IP configuration:

juser@bench2:~/$ curl -k -u admin:admin -H "Content-Type: \application/json" -X POST -d '{"name":"/fw_objs"}' \https://192.168.25.42/mgmt/tm/sys/folder \|python -m json.tool

{"deviceGroup": "none","generation": 0,"hidden": "false","inheritedDevicegroup": "true","inheritedTrafficGroup": "true","kind": "tm:sys:folder:folderstate","lastUpdatedMicros": 0,"name": "/fw_objs","noRefCheck": "false","partition": "/","selfLink": "https://localhost/mgmt/tm/sys/folder/~fw_objs?$partition=/",

"trafficGroup": "Common/traffic-group-1"}

Deleting a partition

A DELETE operation has no JSON body, so you must specify a partition to be deleted in the URI. Youneed to edit the partition name to avoid confusion between the forward slash characters (/) in the URI andthose in the partition name.

To DELETE a partition, use the tilde character (~) in place of every forward slash (/) in the partitionname. Every partition/folder resides in the sys/folder module, so the URI follows this format:

https://address/mgmt/tm/sys/folder/~partition-name

Where:

• address identifies the BIG-IP® system (for example, 192.168.25.42),• tilde character (~) is used in place of forward slash (/) throughout the URI, and• partition-name is the partition to delete.

The delete operation only succeeds if the partition is empty. You cannot delete the /Common partition.

For example, this iControl®-REST call deletes the /fw_objs partition:

juser@bench2:~/$ 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

As another example, this iControl-REST call deletes the /eu/east/romania partition. Each of thethree forward slash characters (/) is replaced with a tilde character (~):

juser@bench2:~/$ curl -k -u admin:admin -H "Content-Type: \application/json" -X DELETE \https://192.168.25.42/mgmt/tm/sys/folder/~eu~east~romania \|python -m json.tool

44

Adding a partition

Saving configuration files

Several tmsh components support the save command, which you can use to save configuration files forlater use.

Use the POST method, a special URI for save operations, and the apiOptions property to describeany options that you want to use for the save operation.

The URI uses a special module/component path in this format:https://management-ip/mgmt/tm/actions/module-cmpnt-path/save. The/actions segmentappears before the module/component path, and the /save appears at the end of the URI.

Set the apiOptions property to one or more options for the save operation on the given tmsh component;you can use the Traffic Management Shell (tmsh) Reference to find all valid options and settings for anygiven component. Use a semi-colon (;) to separate an option name from its setting.

For example, the following curl command saves the system configuration (sys/config) for allpartitions (partitions;all):

juser@bench2:~/$ curl -k -u admin:admin -H "Content-Type: \application/json" -X POST -d \'{"apiOptions":"partitions;all"}' \https://192.168.25.42/mgmt/tm/actions/sys/config/save \|python -m json.tool

{"apiOptions": "partitions;all"

}

46

Saving configuration files

About HTTP response codes

The iControl® REST service (icrd) returns one of the following response codes in each of its HTTPresponses.

Success responses

DescriptionResponse code

This indicates success for all methods, including DELETE.200 OK

Error responses

DescriptionHTTPmethods

Response code

The HTTP request was malformed. This is also the error when yourequest a resource by name and the name is incorrect.

all400 Bad Request

Either the HTTP authorization header is missing or the administratorcredentials do not have sufficient permission to perform the given

all401 Unauthorized

method on the given object. If you use an administrative account otherthan admin to access iControl REST, you get this error..

The administrator credentials do not have sufficient permission toperform the given method on the given object.

all403 Forbidden

The requested resource does not exist in the database. This can occurif you attempt to access a resource after deleting it. See Deleting a

all404 Not Found

configuration object for instructions about deleting an iControl-RESTresource.

There is a conflict between the requested state change and the currentstate of the resource. For example, this is the error response if you

POST, PUT409 Conflict

POST a resource that already exists. See Adding new configurationsfor instructions about adding an iControl-REST resource.

The request body, the value of the -d option in a curl command, isunknown to the server. The body of each request must be in JSON

POST, PUT415 UnsupportedMedia Type

format. For methods with a JSON body, such as POST and PUT, youmust declare the format; see JSON format for POST and PUT for thesyntax to declare this in a curl command.

The software failed to process a response. This may indicate a softwareissue.

all500 Internal ServerError

The iControl REST service received a request for a non-standard tmshcommand that is not supported. Standard tmsh commands are create,

POST501 NotImplemented

modify, delete, list, and show. Non-standard commands includeinstall and generate. The iControl REST service only supportsthe non-standard save command (see Saving configuration files).

48

About HTTP response codes

About log files

From the console or an SSH connection to your BIG-IP® device, you can find the following log files foriControl® REST:

• /var/log/restjavad-audit.0.log shows all authentications to the iControl REST service. Thisis 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 theREST calls.

• /var/log/ltm contains messages from mcpd, a process called by icrd that manages the systemconfiguration.

Use standard Unix commands to work with these files, such as tail, grep, and less. In this example, thesession logs in to a BIG-IP system through ssh and uses tail -f to monitor the/var/log/restjavad-audit.0.log log file:

juser@bench2:~/$ ssh [email protected]: defaultLast 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"}

[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/).

50

About log files

Index

A

Actionsnon-standard 45

apiDecoratedName 39

C

camel casefor JSON properties in iControl REST 15

D

DELETEwith iControl REST 40

deleting configuration objectswith iControl REST 40

E

Error codesin iControl REST responses 47

Expanding an iControl REST componentlimits 27

Expanding an iControl-REST component 24

F

Flags in tmshshow as null in iControl-REST returns 15

FolderSee also Partition

relative to parent's partition 39See also Partition

formatfor JSON properties in iControl REST 15

I

iControl RESTadding service 7discovering modules and components 19log files 49modifying configuration through 34POST 33showing status 7starting 8stopping 8

icrdlog files 49

J

JSONgetting show content instead of list content 29

JSON format11, 17

for iControl REST components 13

L

Logging levelscontact Support to change 49

Logsfor iControl REST 49

M

Modify a single object in a collection 37Modify collection within a config object 34

P

Paging 22Partition

accessing 28adding 43adding or modifying in 38deleting 43

PATCH, See PUTPOST

to BIG-IP config, with iControl REST 33working around a forward slash character in the objectname 39

public URIs 10PUT

in iControl REST 34

R

Read-only propertiessilently ignored in PUT and POST operations 37

Response codesin iControl REST responses 47

S

Save fileswith iControl REST 45

T

tmshGeneration 17tmshName 17

U

URI format 9

51

Index

52

Index

Documents

iControl® REST User Guide - F5 Networks · iControl® REST User Guide Version 11.4. Table of Contents Legal Notices ... ARX,AskF5,ASM,BIG-IP,BIG-IQ,CloudExtender,CloudFucious,CloudManager,Clustered